@sema-agent/server 7.52.0 → 7.53.0

package/dist/config-catalog.d.ts

@@ -0,0 +1,139 @@
+/**
+ * DESIGN-278 §5 S2([ref])—— 配置目录本体:`GET /v1/config/catalog` 的数据层。
+ *
+ * ## 形
+ * 目录 = **逐 env 键**一行(分母 = 全 `src/` 生产运行时的 env 读取点;完备性由
+ * `test/config-catalog.test.ts` 的 D1 双向 AST 对账门执法 —— 多一行是幽灵键、少一行是漏登记,两个方向
+ * 都当场红)。每行静态登记 `{域、类型、一句话语义、staticDefault?/derivedDefaultNote?、危险轴、center
+ * 联接(domain/path/优先序/时机)}`,运行期由 {@link buildConfigCatalog} 补上**本进程实算**的
+ * `{envHeld、effectiveLane、effectiveValue、center.managedNow/effectiveNow/domainExists}`。
+ *
+ * ## 词表纪律([ref]:闭集,未知词=编译红)
+ *  · 类型 {@link CATALOG_VALUE_TYPES} / 时机 {@link CATALOG_TIMINGS} / 危险轴 {@link CATALOG_DANGER_AXES}
+ *    全是 `as const` 闭集;restart 片集 {@link CATALOG_RESTART_SLICES} 用 `Record<RestartSlice, true>`
+ *    锁步 —— core/config-center 的片集变了,这里不改就 tsc 红。
+ *  · 域 = `ServiceConfigGroups` 的九组键(类型锁步,不自铸第二份分组)。
+ *
+ * ## secret 纪律(设计稿 §0.5 补偿条款)
+ *  `secret` 类值**永不出本模块**(只回 `{present}`);`opaque` 类(策略 JSON/公钥表/证书)回
+ *  `{present, length}`;`url` 类剥 userinfo(config 实算腿与 env 原文腿同裁)。机器钉 =
+ *  test/config-catalog.test.ts 的响应体 canary 扫描格 + 名字启发式兜底格。
+ *
+ * ## 生效时机模型(设计稿 §3:标注是「键 × 写入通道」的属性)
+ *  env 腿恒 `deploy`(env 在运行期不可变;retired/无消费键标 `inert`);center 腿按域:limits 热
+ *  (costQuotaWindowSec 除外 —— 显式 deferred,铸因 `cost-quota-window`)、governance 热二件、
+ *  approvalRequire 走 `runtime-gates` 重启片、readFace 族 `read-face` 片且 **env-wins**(⚪ 成因 a)、
+ *  models 面 **本进程实算**(tier 表在场 ⇒ restart/models-tiers,tier-less ⇒ hot)。
+ *  readFace 在 settings-schema 现行 DOMAINS 里**没有域**(R-15:暂不开)⇒ `domainExists:false`,
+ *  writeLanes 不含 center(⚪ 成因 b 的诚实呈现)。
+ */
+import type { ServiceConfig, ServiceConfigGroups } from "./config-types.js";
+import type { ConfigKnobRecord } from "./config.js";
+import type { RestartSlice } from "./config-center/restart-signal.js";
+export declare const CATALOG_VALUE_TYPES: readonly ["boolean", "number", "string", "enum", "csv", "json", "path", "url", "secret", "opaque"];
+export type CatalogValueType = (typeof CATALOG_VALUE_TYPES)[number];
+export declare const CATALOG_TIMINGS: readonly ["hot", "restart", "deploy", "inert"];
+export type CatalogTiming = (typeof CATALOG_TIMINGS)[number];
+export declare const CATALOG_DANGER_AXES: readonly ["security", "billing", "data"];
+export type CatalogDangerAxis = (typeof CATALOG_DANGER_AXES)[number];
+/** 域 = 配置九组(类型锁步:组集变了这里跟着红)。 */
+export type CatalogDomain = keyof ServiceConfigGroups;
+export declare const CATALOG_RESTART_SLICES: readonly RestartSlice[];
+/** center 联接座(spec 层)。`models-plane` 是内部时机词:build 时按 tier 表在场性实算成 hot/restart。 */
+export interface CatalogCenterSeatSpec {
+    readonly domain: string;
+    readonly path: string;
+    /** `centerManagedKeys`(config-center 在管键集)里查「在管」用的键;models 面统一 "models"。 */
+    readonly centerKey: string;
+    readonly precedence: "center-wins" | "env-wins";
+    readonly timing: "hot" | "restart" | "inert" | "models-plane";
+    readonly restartSlice?: RestartSlice;
+    readonly restartReason?: string;
+}
+export type CatalogValue = string | number | boolean | readonly string[] | null | {
+    readonly present: boolean;
+    readonly length?: number;
+};
+export interface ConfigCatalogSpec {
+    readonly name: string;
+    readonly domain: CatalogDomain;
+    readonly type: CatalogValueType;
+    readonly semantics: string;
+    readonly staticDefault?: string;
+    readonly derivedDefaultNote?: string;
+    readonly danger?: readonly CatalogDangerAxis[];
+    readonly enumValues?: readonly string[];
+    /** `ServiceConfig` 的平铺键(实算兜底 + center managedNow 判据对表用;嵌套块不填,走 resolve)。 */
+    readonly configKey?: string;
+    /** 本进程实算(非 secret/opaque 行才可用;返回 undefined = 本行没有实算腿,落 env 原文/staticDefault)。 */
+    readonly resolve?: (config: ServiceConfig) => CatalogValue | undefined;
+    readonly center?: CatalogCenterSeatSpec;
+    /** 缺省 "deploy";retired/零消费键标 "inert"(设计稿 ⚪ 的 env 腿投影)。 */
+    readonly envTiming?: "inert";
+    readonly scope?: "bootstrap-only";
+}
+export interface ConfigCatalogRowCenter {
+    readonly domain: string;
+    readonly path: string;
+    readonly precedence: "center-wins" | "env-wins";
+    readonly timing: Exclude<CatalogTiming, "deploy">;
+    readonly restartSlice?: RestartSlice;
+    readonly restartReason?: string;
+    /** settings-schema 现行 DOMAINS 里真有这个域(false = 设计稿 ⚪ 成因 b「该片暂无配置中心写腿」)。 */
+    readonly domainExists: boolean;
+    /** center 的最近一份 effective **当前在管**本键(没有配置管道 ⇒ 恒 false)。 */
+    readonly managedNow: boolean;
+    /** center 写**现在真的在生效**(在管 ∧ 未被 env 占位压住;env-wins 族 env 占位 ⇒ false = ⚪ 成因 a)。 */
+    readonly effectiveNow: boolean;
+}
+export interface ConfigCatalogRow {
+    readonly name: string;
+    readonly domain: CatalogDomain;
+    readonly type: CatalogValueType;
+    readonly semantics: string;
+    readonly writeLanes: readonly ("env" | "center")[];
+    readonly effectiveLane: "env" | "center" | "default";
+    readonly envHeld: boolean;
+    readonly envTiming: "deploy" | "inert";
+    readonly staticDefault?: string;
+    readonly derivedDefaultNote?: string;
+    readonly effectiveValue: CatalogValue;
+    readonly valueClass: "plain" | "secret" | "opaque";
+    readonly danger: readonly CatalogDangerAxis[];
+    readonly center?: ConfigCatalogRowCenter;
+    readonly centerDomain?: string;
+    readonly centerPath?: string;
+    readonly scope?: "bootstrap-only";
+    readonly enumValues?: readonly string[];
+}
+export interface ConfigCatalogInputs {
+    readonly config: ServiceConfig;
+    readonly env: NodeJS.ProcessEnv;
+    readonly knobs: readonly ConfigKnobRecord[];
+    /** settings-schema 现行 DOMAINS(调用方传入 —— 本模块保持纯数据层,零包依赖)。 */
+    readonly centerDomains: readonly string[];
+    /** config-center 当前在管的 ServiceConfig 键集(缺席 = 没有配置管道)。 */
+    readonly centerManagedKeys?: ReadonlySet<string> | undefined;
+}
+export interface ConfigCatalogWire {
+    readonly catalogVersion: 1;
+    /** env 腿的统一时机(env 运行期不可变 ⇒ 改 env=改部署面;行级 `envTiming:"inert"` 覆写)。 */
+    readonly envLaneTiming: "deploy";
+    readonly restartSlices: readonly RestartSlice[];
+    readonly centerDomains: readonly string[];
+    readonly summary: {
+        readonly total: number;
+        readonly envHeld: number;
+        readonly secret: number;
+        readonly centerManaged: number;
+    };
+    readonly rows: readonly ConfigCatalogRow[];
+}
+/**
+ * 目录表(按名排序 —— 卫生格执法)。语义句以读取点实现为准(不信注释纪律:本表成文时逐键对过
+ * config.ts / boot / plugins 的真实读取臂;后续漂移由 D1 对账门逼着回到这里补行)。
+ */
+export declare const CONFIG_CATALOG: readonly ConfigCatalogSpec[];
+/** `build*` 命名(工厂纪律):产物是纯数据(wire 投影),零方法零捕获行为。 */
+export declare function buildConfigCatalog(inputs: ConfigCatalogInputs): ConfigCatalogWire;
+//# sourceMappingURL=config-catalog.d.ts.map