@sema-agent/server 7.11.0 → 7.13.0

package/dist/config.d.ts

@@ -46,10 +46,36 @@ export declare function parseNumOrFail(name: string, raw: string | undefined): n
  * existing `|| fallback` chains built on `parseNumOrFail` are untouched by this stricter sibling.
  */
 export declare function parseNumOrFailNonNegative(name: string, raw: string | undefined): number;
-export declare function drainConfigWarnings(): Array<{
+/** Optional FAIL-SAFE numeric env for an OPTIONAL feature knob: a non-numeric / non-positive value yields `undefined`
+ *  (the caller falls back to its own default) rather than NaN OR a hard startup throw. Used for SESSION_SNAPSHOT_TTL_SEC
+ *  (finding 20): a typo like "600s" must NOT sign every presigned URL with X-Amz-Expires=NaN (total snapshot outage),
+ *  but ALSO must not crash boot of an unrelated subsystem — degrade to the MinioBlobBackend default. */
+/** S20 (SILENT-FALLBACK P1): soft-knob parse rejects, collected here because config parsing runs BEFORE the
+ *  logger exists. main.ts drains this once after createLogger and warns per entry ("configured X=raw is
+ *  invalid, using the default"). Module-level on purpose; drain clears it (repeat loadConfig in tests is fine). */
+/**
+ * #210(黑板 [3425]③):一条配置诊断的**种类**。
+ *
+ * ⚠️ 为什么是显式 `kind` 而不是「`used` 在不在场」(codex 自审 R2-F1 真修):第一版拿可选字段当判别式,
+ * 于是三件语义完全不同的事挤在两个出口上 —— 空串**保留原值**被报成「越界夹取」、坏值**回默认**因为带了
+ * 采用值也被报成夹取、而钥集条目**被丢弃**(没有任何采用值、也不该印 raw)却被报成「坏值回默认」。
+ * 告警规则是按事件名分流的,报错的种类就是报错的事实本身;可选字段的在场性是实现细节,不该被当契约用。
+ *
+ * `invalid-default` 是**缺省种类**(不写 `kind` 即是它)—— 历史形 `{env,raw}` 的三个存量生产者
+ * (`optFinitePositiveEnv` / `boolEnv` / `boolEnvWithLegacyNegated`)因此逐字不动,它们的断言也不破。
+ */
+type ConfigWarningKind = "invalid-default" | "clamped" | "empty-preserved" | "entry-rejected" | "set-rejected";
+interface ConfigWarning {
     env: string;
+    /** 环境原文。`entry-rejected` 上恒为脱敏占位 —— 那两条 env 装的是凭据,原文永不进日志。 */
     raw: string;
-}>;
+    /** 真正生效的值(`clamped` 必带;`invalid-default` / `empty-preserved` 可带)。 */
+    used?: string;
+    kind?: ConfigWarningKind;
+    /** `entry-rejected` / `set-rejected` 专用:条目序号 + 缺陷字段名,或整份坏的形状原因(都不带值)。 */
+    detail?: string;
+}
+export declare function drainConfigWarnings(): ConfigWarning[];
 export declare function drainConfigNotices(): Array<{
     event: string;
     fields: Record<string, string>;