servicecontract

type Admission struct {
	// Public — величины публичного слушателя, на ЛИЧНОСТЬ КОНЕЧНОГО
	// ПОЛЬЗОВАТЕЛЯ.
	Public grpcsrv.AdmissionLimits
	// Internal — величины внутреннего слушателя, на ЛИЧНОСТЬ СЕРТИФИКАТА
	// вызывающего модуля.
	Internal grpcsrv.AdmissionLimits
}

type AuthzSource uint8

type Axis[T any] struct {
	// contains filtered or unexported fields
}

type BootGate interface {
	// GuardMutation возвращает отказ, если мутацию принимать нельзя, и nil иначе.
	GuardMutation() error
}

type DeliveryProvenance uint8

type Descriptor struct {
	// contains filtered or unexported fields
}

type ExistenceProbe interface {
	ObjectExists(ctx context.Context, objectType, objectID string) (bool, error)

	// ProbeableTypes — типы объектов, о которых проба УМЕЕТ ответить.
	//
	// # Зачем порт объявляет свой охват, а не отвечает ошибкой по факту
	//
	// Неизвестный тип проба отвергает ошибкой, а вызывающий трактует ошибку как
	// «не могу подтвердить отсутствие» и оставляет отказ отказом (fail-closed).
	// Это верное поведение НА ЗАПРОСЕ и негодное как единственное: пока охват
	// проверяется только запросом, тип, до которого проба не доросла, ведёт себя
	// не как дефект, а как «нет доступа» — то есть неотличимо от исправной
	// работы. Наблюдалось (задача продукта #1931): у compute из трёх пообъектных
	// типов карты прав проба знала ОДИН, и два соседних типа того же сервиса
	// отвечали на одном и том же входе разным кодом.
	//
	// Объявленный охват даёт носителю вторую сторону сравнения, и сравнение
	// становится ВЫВЕДЕННЫМ с обеих сторон: пообъектные типы выводятся из карты
	// прав, охват — из самой пробы. Ни одного выписанного перечня в месте
	// сравнения нет, поэтому расхождение не может пережить правку одной стороны.
	//
	// Отдаётся КОПИЯ либо свежий срез: носитель читает возвращённое и не вправе
	// зависеть от того, что за ним стоит внутренняя карта пробы.
	ProbeableTypes() []string
}

type ForwarderKnobs struct {
	// SANs — имя ручки, которой задаётся круг. Нужно тексту отказа.
	SANs string
	// TrustAny — имя ручки landed-опт-ина. Нужно тексту отказа: сообщение,
	// не называющее ручку, оставляет стенд неподнятым и непонятным.
	TrustAny string
	// OptIn — испрошен ли опт-ин. Передаётся landed-стражу как есть; в боевом
	// режиме страж его НЕ читает. Проверено парой проб: тот же пустой круг с
	// испрошенным опт-ином в боевом режиме остаётся отказом, вне боевого —
	// принимается.
	OptIn bool
}

type ListNarrower = *listnarrow.Narrower

type MethodFQN string

type Mode uint8

type NotFoundFormat string

type ObjectType string

type PeerEdge struct {
	// contains filtered or unexported fields
}

type ServiceName string

type Spec struct {
	// Service — короткое имя процесса.
	Service ServiceName
	// Mode — посадка. Из неё, и только из неё, выводится боевая строгость.
	Mode Mode
	// Logger — журнал процесса. Ноль резолвится в [slog.Default]: журнал —
	// единственное поле, чьё умолчание не является решением о доступе.
	Logger *slog.Logger

	// OwnContour — ПРИЧИНА, по которой контур входящего пути этого процесса
	// поднимает не носитель ([github.com/PRO-Robotech/kacho/pkg/servicehost]), а
	// его собственный композиционный корень. Пустая строка означает «поднимает
	// носитель» и является обычным случаем.
	//
	// # Зачем поле вообще есть
	//
	// [Spec] описывает ДВЕ разные вещи. Первая — ПОСАДКА: режим, шифрование до
	// своей базы, круг отправителей. Она есть у КАЖДОГО развёрнутого процесса, и
	// ровно её требует ban #16. Вторая — ПРОВОДКА НОСИТЕЛЯ: что эмитить, что
	// сужать, что скрывать, какие пределы ставить звеньям. Её читает ТОЛЬКО
	// носитель, и больше никто.
	//
	// Пока поля не было, принять дескриптор мог лишь тот, кто приносит обе
	// половины. Процессы с собственным контуром — фасад личности и внешний край —
	// не могли принести вторую, потому что её некому прочитать, и потому не
	// проходили через единый источник ВОВСЕ: набор осей, которые каждый из них
	// судит, выбирал он сам, а расхождение между наборами было невидимо.
	// Заполнить проводку «правдоподобно» было бы хуже отказа: объявление, которое
	// никто не читает, расходится с фактической ручной сборкой молча.
	//
	// # Почему это НЕ ручка, снимающая проверки
	//
	// Три свойства сразу, и ни одно не держится обещанием:
	//
	//   - ПОСАДКУ поле не трогает: она судится при любом его значении. Снимается
	//     только проводка носителя — то, что при собственном контуре не читает
	//     никто;
	//   - проводка при непустом значении не просто не требуется, а ЗАПРЕЩЕНА
	//     (О14): принесённая и непрочитанная, она была бы вторым местом об одном
	//     предмете, из которых верно одно;
	//   - заявление стоит ПРОЦЕССУ НОСИТЕЛЯ. `servicehost.Serve` отказывает
	//     дескриптору с непустым `OwnContour`, поэтому объявить его ложно значит
	//     собрать весь контур руками — работа, которую нельзя ни сделать
	//     незаметно, ни объяснить удобством.
	//
	// Причина обязана быть непустой по той же причине, по какой её требует
	// [NotApplicable]: изъятие без причины не отличимо от забывчивости.
	OwnContour string

	// Forwarders — круг личностей сертификата, которым разрешено передавать
	// личность конечного пользователя.
	//
	// Семантика нулевого значения ВНУТРИ оси — «круг НЕ сужен»: это действующая
	// семантика общей библиотеки, и тип её не переопределяет. «Забыл настроить»
	// ловит отказ старта (О1) по ТОМУ ЖЕ предикату `IsNarrowed()`, который
	// читает транспорт, а не смена смысла пустого множества.
	//
	// # Почему ОСЬ, а не поле (введено вместе с переводом края, задача #1407)
	//
	// Пока это было поле, «круг не сужен» и «принимать переданную личность
	// НЕКОМУ» записывались ОДНИМ И ТЕМ ЖЕ нулевым значением, а отличаются они
	// ровно тем, ради чего страж заведён. Процесс, который переданную личность
	// не принимает, а ОТПРАВЛЯЕТ, сужать ему нечего: у него нет ни ручки круга,
	// ни звена, которое его прочтёт. Полем такое состояние выражается только
	// выдуманным непустым кругом — то есть объявлением защиты, которой нет.
	//
	// Изъятие ИСТЕКАЕТ САМО и не памятью автора: обход дерева
	// (`internal/repohygiene.TestServiceDeclaringPostureKnobsHasABootGuard`)
	// требует, чтобы компонент, объявивший ось неприменимой, НЕ объявлял её
	// ручек. Появится у него ручка круга — изъятие станет находкой.
	Forwarders Axis[grpcsrv.TrustedForwarders]

	// TrustDomain — домен доверия установки: то, чьи сертификаты она признаёт
	// своими. Круг отправителей называет, КОМУ позволено говорить за
	// пользователя; домен — чьи вообще предъявители наши.
	//
	// # Почему ОСЬ, а не поле
	//
	// По той же причине, что у соседки: «домен не объявлен» и «личность
	// сертификата этот процесс не разбирает» записывались бы одним нулевым
	// значением, а отличаются они ровно тем, ради чего страж заведён. Процесс,
	// поднимающий контур САМ, вправе не разбирать личность вовсе; процесс,
	// чей контур поднимает носитель, разбирает её всегда — носитель ставит пару
	// звеньев извлечения безусловно и на обоих слушателях.
	//
	// Семантика нулевого значения ВНУТРИ оси — «домен не назван», и она
	// фейл-клоуз: по необъявленному домену не опознаётся ни один предъявитель.
	// Умолчания у домена нет и быть не может: непустое умолчание сделало бы
	// контроль на вид включённым и увело бы установку, забывшую назвать свой
	// домен, в чужой (`security.md` §«Адрес зависимости… НЕ выводится из чужого»).
	TrustDomain Axis[grpcsrv.TrustDomain]
	// TrustDomainKnob — имя ручки для текста отказа. Читается только там, где
	// [Spec.TrustDomain] несёт значение: у процесса, не разбирающего личность,
	// ручки нет, и называть её в отказе было бы нечем.
	TrustDomainKnob string

	// ForwarderKnobs — имена ручек для текста отказа и dev-опт-ин. Читаются
	// только там, где [Spec.Forwarders] несёт значение: у процесса без круга
	// ручек нет, и называть их в отказе было бы нечем.
	ForwarderKnobs ForwarderKnobs

	// Authz — кто принимает решение о доступе.
	Authz AuthzSource
	// CheckEdge — ребро к владельцу модели. Обязательно при [AuthzViaIAM].
	CheckEdge PeerEdge
	// SelfCheck — решатель ВЛАДЕЛЬЦА модели. Обязателен при [AuthzSelf] и
	// запрещён при [AuthzViaIAM].
	//
	// Поле существует затем, чтобы «сам себе владелец» не оказалось веткой,
	// которую носитель не умеет поднять. Пара с [Spec.CheckEdge] исчерпывающая и
	// взаимоисключающая: у каждого источника решения ровно один способ его
	// принести, и перепутать их нельзя — оба судятся [New].
	SelfCheck authz.CheckClient
	// PeerCheck — СБОРЩИК решателя из соединения с владельцем модели.
	// Обязателен при [AuthzViaIAM] и запрещён при [AuthzSelf].
	//
	// # Почему сборщик приносит сервис, а не носитель делает его сам
	//
	// Перевод вопроса о доступе в контракт владельца — знание о КОНТРАКТЕ
	// СЛУЖБЫ ДОСТУПА, а носитель принадлежит фундаменту. Пока адаптер жил в
	// носителе, фундамент импортировал этот контракт: после разъезда на три
	// модуля `corelib` потребовал бы `kaname`, который уже требует `corelib`, —
	// цикл, который Go не собирает (приёмка K3-1 §7.2, задача #2131).
	//
	// Носитель по-прежнему сам НАБИРАЕТ соседа по объявленному ребру
	// ([Spec.CheckEdge]) и сам закрывает соединение: посадку ребра судит эта же
	// проверка, и ребро, которое никто не набирает, стало бы объявлением без
	// предмета. Наружу вынесено ровно одно — перевод в чужой контракт.
	//
	// Пара с [Spec.SelfCheck] остаётся исчерпывающей и взаимоисключающей: у
	// каждого источника решения ровно один способ его принести.
	PeerCheck authz.CheckClientFrom
	// CacheWindow — окно кэша положительных вердиктов, оно же ОКНО ОТЗЫВА:
	// столько субъект, у которого право уже отобрали, продолжает проходить.
	// Умолчания нет: параметр безопасности, которого никто не выбирал, нельзя
	// ни обсудить, ни сузить на конкретной посадке.
	CacheWindow time.Duration
	// ClientBudget — срок одного вопроса владельцу модели. Умолчания нет по той
	// же причине.
	ClientBudget time.Duration
	// DenyBudget — устойчивый темп проверок (в секунду на принципала), чей исход
	// кэш НЕ поглощает: отказ, сокрытие существования, промах «нет пути» и
	// недоступность модели. По исчерпании звено отвечает `ResourceExhausted`, не
	// обращаясь к владельцу модели, — то есть сбрасывает шторм с него.
	//
	// # Почему ОСЬ, а не число, и почему нулю здесь не место
	//
	// Механизм (`pkg/authz`) читает ноль как «ограничения нет»: при `ratePerSec
	// <= 0` бюджет есть всегда. Значит незаполненное поле МОЛЧА выключило бы
	// отсечку, ветка `DecisionRateLimited` стала бы недостижимой, а её счётчик —
	// навсегда нулевым; заметить пропажу нечем, потому что «шторма не было» и
	// «отсечки не было» выглядят одинаково.
	//
	// Поэтому три состояния вместо двух: величина (строго больше нуля),
	// «не применимо, потому что …» с непустой причиной — либо отказ старта.
	// Выключить отсечку по-прежнему можно, но только НАЗВАВ причину, и причина
	// видна в обзоре, а не выводится из пустоты. Законный повод у неё есть:
	// владелец модели решает У СЕБЯ ([AuthzSelf]), и сетевого соседа, которого
	// шторм мог бы уронить, у него нет.
	DenyBudget Axis[float64]

	// AuthzObserve — приёмник читателя величин КЕША ПОЛОЖИТЕЛЬНЫХ ВЕРДИКТОВ.
	// Носитель зовёт его ровно один раз, собрав звено решения, и передаёт
	// функцию, читающую счётчики ТОГО звена — вместе с величинами окна вердиктов,
	// которое оно спрашивает.
	//
	// # Почему это поле, а не «корень сам достанет»
	//
	// Кеш строит носитель ([servicehost]), а диагностическую поверхность держит
	// композиционный корень. Достать величины корню НЕ ИЗ ЧЕГО: `Serve` не
	// возвращает ни сервера, ни звена — это то же свойство построения, которым
	// у сервиса отобрана возможность собрать свою цепочку. Значит переход через
	// границу обязан быть объявлен, и объявлен здесь.
	//
	// # Почему обязательное, а не «поставит тот, кому надо»
	//
	// Доля попаданий — единственное число, которым отвечают на вопрос «сколько
	// даёт кеш», и без неё утверждение о кеше непроверяемо В ОБЕ СТОРОНЫ: кеш,
	// не попадающий ни разу, снаружи неотличим от кеша, поглощающего весь поток.
	// Пока поле было бы необязательным, шесть процессов из шести не выставляли
	// бы его — что и наблюдалось: величины существовали, читателя не имел ни
	// один. Умолчанием тут была бы тишина, а тишина о параметре, вокруг которого
	// принимают решения, — не умолчание, а отсутствие предмета разговора.
	//
	// Пустая функция конструктор пройдёт: он судит объявление, а не то, куда
	// величины уехали. Вторую половину держит обход дерева
	// (`internal/repohygiene.TestEveryCarrierServiceExportsItsVerdictCacheHitRate`):
	// сервис у носителя обязан строить коллектор `pkg/authz/authzmetrics`.
	AuthzObserve func(read func() authz.Metrics)

	// Metrics — реестр, в котором носитель заводит измеритель ЗАДЕРЖКИ
	// обслуженного вызова (`pkg/grpcsrv.ServerLatency`).
	//
	// # Почему поле, а не «сервис померит у себя»
	//
	// Тот же довод, которым здесь стоят пределы слушателя и круг отправителей:
	// пока гистограмму заводит каждый сервис у себя, «не завёл» НЕОТЛИЧИМО от
	// «завёл такую же». Отсутствие серии ничего не печатает, слушатель
	// поднимается молча, и узнают об этом ровно тогда, когда задержку
	// понадобилось посмотреть, — то есть в разборе происшествия, когда данных
	// уже не будет.
	//
	// # Почему ОБЯЗАТЕЛЬНОЕ, а не Axis
	//
	// У [Axis] тип берут оси, у которых «пусто» бывает ЗАКОННЫМ ответом. Здесь
	// такого ответа не существует: всякий слушатель служит вызовы, и у всякого
	// вызова есть длительность. Сервиса, которому задержка «не применима», не
	// бывает — значит и клетки «не применимо, потому что …» заводить не из чего.
	//
	// # Почему судится на ЛЮБОЙ посадке, а не только на боевой
	//
	// Соблазн — освободить dev: там-де метрики никто не скребёт. Освобождение
	// снимает предмет целиком. Во-первых, посадка стенда в этом продукте и так
	// боевая (правило «production-mode ВЕЗДЕ»), то есть освобождать нечего.
	// Во-вторых, стенд разработчика — ровно то место, где задержку меряют перед
	// тем, как что-нибудь про неё утверждать; освободив его, мы получили бы
	// процесс, у которого «не наблюдает» неотличимо от «наблюдает», в
	// единственной посадке, где на это смотрят руками.
	//
	// Отличие от [Spec.Forwarders] (О1), где строгость ЗАВИСИТ от режима,
	// намеренно: там у послабления есть предмет — dev-фикстура законно говорит
	// за кого угодно, и цена сужения реальна. Здесь цена соблюдения — одна
	// строка (`prometheus.NewRegistry()`), а выгода послабления нулевая.
	// Послабление без предмета — это просто выключенный контроль.
	//
	// # Почему реестр, а не готовый измеритель
	//
	// Принеси сервис собранный измеритель — он мог бы собрать его над реестром,
	// который никто не скребёт, и отказ старта этого не увидел бы. Реестр же
	// заводит серии РУКАМИ НОСИТЕЛЯ: несогласованное объявление (то же имя с
	// другой размерностью) становится отказом подъёма, а не молчаливой пропажей
	// семейства с диагностической поверхности.
	//
	// Пустой реестр конструктор пройдёт: он судит объявление, а не то, скребёт
	// ли кто-нибудь эту поверхность. Вторую половину держит обход дерева
	// (`internal/repohygiene.TestEveryGRPCListenerObservesItsLatency`).
	Metrics prometheus.Registerer

	// HandlingBudget — верхняя граница обработки ОДНОГО вызова: если у входящего
	// контекста срока нет либо он дальше границы, носитель ставит свой. Более
	// строгий срок вызывающего уважается — окно не расширяется никогда.
	//
	// Обязательное поле БЕЗ «не применимо», и отличие от [Spec.DenyBudget]
	// намеренное: состояния «границы нет» как посадки не существует. Вызов без
	// срока держит соединение из ограниченного пула столько, сколько выполняется
	// его запрос, поэтому `MaxConns` таких вызовов исчерпывают пул и отказывает
	// весь сервис (CWE-770). Сказать «мне граница не нужна» значит сказать «мой
	// процесс вправе держать чужой ресурс сколько угодно».
	//
	// Величина накрывает ТОЛЬКО одиночный вызов. Для серверного стрима она не
	// применяется вовсе — у подписки своя ось, [Spec.StreamBudget].
	HandlingBudget time.Duration

	// StreamBudget — СРОК ЖИЗНИ СЕРВЕРНОГО СТРИМА: столько живёт подписка,
	// прежде чем носитель оборвёт её истечением контекста.
	//
	// # Почему это ОТДЕЛЬНАЯ величина, а не та же самая
	//
	// «Верхняя граница обработки» и «срок жизни подписки» — разные предметы, и
	// общее у них только название единицы. Обоснование [Spec.HandlingBudget]
	// говорит про исчерпание пула соединений ЗАПРОСАМИ; подписка держит
	// соединение по построению, столько, сколько клиент хочет слушать события, и
	// граница, взятая от одиночного вызова, рвала бы её каждые полминуты — причём
	// клиент видел бы это как СЕТЕВОЙ СБОЙ, а не как наш отказ. Одно правило на
	// два вида вызовов с принципиально разным сроком жизни — это намеренно узкая
	// семантика, прочитанная за общий случай.
	//
	// # Три состояния, и каждое СУДИТСЯ служимым набором
	//
	//   - величина — стрим-цепочка накрывается ЕЮ (не границей обработки);
	//   - «не применимо, потому что …» — стрим-цепочка границей не накрывается
	//     вовсе, и это законно ровно пока процесс не служит ни одного серверного
	//     стрима: появился первый — заявление истекло, старт отказан (О11);
	//   - не объявлена — [New] отказывает (О10).
	//
	// Обратная сторона — величина у процесса БЕЗ служимых стримов — тоже находка
	// ([servicehost] О11): это проводка без предмета, и без неё ось ловила бы
	// форму («что-то объявлено»), а не существо («объявлено про то, что есть»).
	//
	// # Почему величина обязана ПРЕВОСХОДИТЬ границу обработки
	//
	// Значение, не большее [Spec.HandlingBudget], возвращает ровно тот разрыв,
	// ради устранения которого ось заведена, — только теперь с виду осознанно:
	// подписка обрывалась бы не позже, чем истекает потолок ОДИНОЧНОГО вызова.
	// Такое объявление неотличимо от «взяли унарную величину», а отличие как раз
	// и есть предмет оси, поэтому оно отвергается [New] с названной причиной.
	StreamBudget Axis[time.Duration]

	// Admission — ПОТОЛОК ТЕМПА и ОДНОВРЕМЕННОСТИ на вызывающего, по одному
	// набору на слушатель.
	//
	// # Почему ось, а не поле с умолчанием
	//
	// Механизм жил в фундаменте (`pkg/grpcsrv/admission.go`) и был провязан у
	// ОДНОГО места сборки сервера из десяти, причём заметить это можно было
	// только сплошной переписью. Поле с умолчанием повторило бы историю:
	// следующий процесс поднялся бы без потолка и выглядел бы в точности как с
	// потолком. Ось убирает «забыл» как исход — сказать про потолок обязан
	// каждый, а сказанное судится здесь.
	//
	// # Почему наборов ДВА
	//
	// У слушателей разные вызывающие и разная цена ошибки: публичный зовёт
	// арендатор через край (ключ — личность конечного пользователя), внутренний
	// зовут наши же модули по проверенному сертификату (ключ — личность
	// СЕРТИФИКАТА, потому что запрос модуля несёт личности разных арендаторов).
	// Общий набор был бы решением, принятым за оба сразу.
	//
	// # Что здесь законно
	//
	// Величины — от посадки либо пол платформы
	// ([grpcsrv.PlatformPublicAdmission] / [grpcsrv.PlatformInternalAdmission]);
	// изъятие `NotApplicable` — только ВНЕ боевого режима (внутрипроцессная
	// фикстура, чьи слушатели наружу не выставлены). На боевой посадке «потолка
	// не надо» означает «один арендатор вправе занять сервис чтением», и это
	// отвергается вместе с остальной боевой строгостью.
	Admission Axis[Admission]

	// DBSSLMode — режим шифрования до собственной БД (`sslmode`).
	//
	// # Почему ОСЬ, а не строка (введено вместе с переводом края, задача #1407)
	//
	// Пустая строка означала бы `disable` — то есть открытый канал, — и на
	// боевой посадке отвергалась бы. Процессу БЕЗ собственной базы отвечать на
	// этот вопрос нечем: любое значение, которое он подставит, будет
	// утверждением о соединении, которого он не открывает. Строкой это
	// выражается только правдоподобной константой («require»), и она проходит
	// стража всегда, ничего при этом не описывая.
	//
	// Изъятие ИСТЕКАЕТ САМО: обход дерева требует, чтобы компонент, объявивший
	// ось неприменимой, не объявлял ручки `*_DB_SSLMODE` / `ssl-mode`. Заведёт
	// базу — заведёт ручку, и изъятие станет находкой.
	DBSSLMode Axis[string]
	// PublicAddr / InternalAddr — адреса публичного и внутреннего слушателей.
	PublicAddr, InternalAddr string
	// PublicCreds / InternalCreds — транспорт слушателей. Внутренний НЕ
	// освобождён: «internal = доверенный» — запрещённое допущение.
	PublicCreds, InternalCreds credentials.TransportCredentials

	// Emits — отношения, которые сервис эмитит владельцу прав. Элемент —
	// половина решения: приём судится ТРОЙКОЙ (субъект · отношение · тип
	// объекта) правилом `proxytuple.ValidateTuple`, а не членством в наборе.
	Emits Axis[[]proxytuple.Relation]
	// Registers — типы объектов, которые сервис регистрирует у владельца прав.
	Registers Axis[[]ObjectType]
	// Narrowers — ПРОВОДКА сужателя по методу. Перечень сужаемых методов даёт
	// каталог; здесь только реализация, и подставить свою нельзя.
	Narrowers Axis[map[MethodFQN]ListNarrower]
	// HideExistence — форма отказа для типов, чьё существование скрывается.
	HideExistence Axis[map[ObjectType]NotFoundFormat]
	// Delivery — происхождение намерений регистрации. Судится осью [Spec.Emits].
	Delivery Axis[DeliveryProvenance]

	// Existence — порт «есть ли объект в моей базе». Судится осью
	// [Spec.HideExistence]: объявлено скрытие — обязателен, не объявлено —
	// запрещён.
	Existence ExistenceProbe
	// BootGate — загрузочный гейт мутаций: создание ресурса принимается только
	// при поднятом пути доставки намерений регистрации.
	//
	// # Почему ось, а не «nil значит гейта нет»
	//
	// Пока поле было указателем, у него не было ЧИТАТЕЛЯ вовсе: объявлено,
	// провязано в трёх сервисах из семи, и ни одна строка носителя его не
	// спрашивала. Со стороны обзора это выглядело исполненной работой, а на деле
	// в окне, когда дренаж не поднят, ресурсы создавались без доставляемого
	// намерения — то есть без владельца. Отличить «гейта нет, потому что очереди
	// нет» от «гейт забыли принести» по `nil` было нечем, и это ровно та
	// неразличимость, ради которой заведён [Axis].
	//
	// Судится соседкой в ОДНУ сторону: гейт, принесённый сервисом, который ничего
	// не эмитит, — находка (проводка без предмета). Обратная сторона — эмитент
	// БЕЗ гейта — сегодня отказом НЕ является, и это названо, а не умолчано:
	// на дереве два эмитента гейта не несут (`git grep -l 'bootgate\.'
	// services/*/cmd services/*/internal` — vpc, compute, nlb и никто больше),
	// поэтому такой отказ закрыл бы им перевод раньше, чем у них появится гейт.
	// Пустая клетка при этом молчаливой не остаётся: закрыть ось можно только
	// [NotApplicable] с причиной, а причина видна в обзоре.
	BootGate Axis[BootGate]
}

type Surface struct {
	// Service — короткое имя процесса. Попадает в журнал и в текст отказа.
	Service ServiceName
	// Name — имя поверхности внутри процесса. См. [SurfaceName].
	Name SurfaceName
	// Mode — посадка процесса. Читается самоотчётом при подъёме: посадка,
	// объявленная процессом, — то, что сверяет гейт стенда.
	Mode Mode
	// Logger — журнал. Ноль резолвится в [slog.Default].
	Logger *slog.Logger

	// Addr — адрес слушателя, и ТРИ его состояния вместо двух.
	//
	// Пустая строка в этом дереве означала «поверхность выключена», и означала
	// это МОЛЧА: профиль развёртывания, забывший задать эндпоинт, был неотличим
	// от посадки, где скрейпа нет намеренно. У шести из одиннадцати слушателей
	// это выглядело как ветка `if addr == ""` без единого слова о том, законно ли
	// сюда попадать; у одного (реестр) рядом стояло предупреждение, и оно же
	// доказывает, что различие кому-то было нужно.
	//
	// Поэтому: [Value] с непустым адресом — поднимаем; [NotApplicable] с
	// причиной — выключено ОБЪЯВЛЕНИЕМ, причина видна в журнале и в обзоре;
	// необъявленная ось и `Value("")` — отказ (Н3).
	Addr Axis[string]
	// Handler — что обслуживается. Обязателен при включённой поверхности (Н8).
	Handler http.Handler
	// TLS — транспорт слушателя. `nil` — открытый текст.
	//
	// Отказа «боевая посадка и открытый текст» здесь НЕТ, и это названо, а не
	// умолчано: у внешних поверхностей этого продукта TLS терминируется на входе
	// кластера, то есть шифрование хопа — факт РАЗВЁРТЫВАНИЯ, которого процесс не
	// знает. Отказ, выведенный из незнания, отказал бы верной посадке.
	TLS *tls.Config

	// Reach — откуда досягаема. Обязательна (Н4).
	Reach SurfaceReach
	// Auth — РЕШЕНИЕ ОБ АУТЕНТИФИКАЦИИ, объявленное данными.
	//
	// Три состояния, и среднее — весь смысл оси:
	//
	//   - [Value] — аутентификация есть, и значение НАЗЫВАЕТ ЧЕМ;
	//   - [NotApplicable] — её нет, и причина названа. Так объявляется
	//     задокументированное исключение (метрики; зеркало публичных ключей
	//     проверки, `security.md` §AuthN+AuthZ ВЕЗДЕ);
	//   - не объявлена — отказ старта (Н5).
	//
	// Почему отказ, а не умолчание в любую сторону: умолчание «нет» дало бы
	// незащищённую поверхность, поднятую молча, а умолчание «есть» — ложное
	// объявление о защите, которой нет. Различить забытое от снятого осознанно
	// можно только тем, что снятие ТРЕБУЕТ слов, а забытое их не имеет.
	Auth Axis[SurfaceAuthMech]

	// ReadHeaderBudget — сколько ждать ЗАГОЛОВОК запроса. Обязателен (Н9): без
	// него медленный отправитель держит соединение сколько угодно, ничего не
	// прислав, — и поверхность падает от одного клиента.
	ReadHeaderBudget time.Duration
	// RequestBudget — потолок чтения и записи ВСЕГО запроса.
	//
	// Ось, а не обязательное поле, потому что у потоковой поверхности его быть
	// НЕ ДОЛЖНО: слой образа едет минутами, и потолок записи разорвал бы
	// исправную передачу. «Не применимо, потому что …» — законное объявление,
	// а необъявленность — отказ (Н10). Величина, не большая [ReadHeaderBudget],
	// бессмысленна и тоже отказ (Н11): потолок запроса не бывает уже потолка его
	// заголовка.
	RequestBudget Axis[time.Duration]
	// IdleBudget — сколько живёт ПРОСТАИВАЮЩЕЕ keep-alive соединение.
	//
	// Обязателен (Н12) и отличается от [RequestBudget] предметом: там потолок
	// работы, здесь — потолок безделья. Ноль в stdlib означает «взять потолок
	// чтения», а при неназванном потолке чтения — «не ограничивать вовсе»;
	// то есть незаполненное поле МОЛЧА снимало бы ограничение ровно на той
	// поверхности, где оно нужнее всего (потоковой, у которой потолка чтения нет
	// намеренно).
	IdleBudget time.Duration
	// ShutdownBudget — сколько ждать завершения начатых запросов при гашении.
	//
	// Обязателен (Н13). Гашение без срока — не гашение: две поверхности этого
	// дерева гасились контекстом БЕЗ срока, то есть процесс на остановке ждал
	// последнего скрейпа неограниченно, и уносил его только внешний убийца.
	ShutdownBudget time.Duration
}

type SurfaceAuthMech string

type SurfaceDescriptor struct {
	// contains filtered or unexported fields
}

type SurfaceName string

type SurfaceReach uint8