@geoly-ai/social-hub-sdk 0.0.46 → 0.0.48

package/dist/index.d.ts

@@ -475,6 +475,75 @@ export type ListAuditLogsParams = {
     createdFrom?: string;
     createdTo?: string;
 };
+/** `GET /v1/teams/:teamId/permissions-matrix/revisions` 的查询参数（迁移 0128）。 */
+export type PermissionsMatrixRevisionsParams = {
+    /**
+     * 只查一张轨迹表。省略 = 两张都查。
+     * 给了 `action` 隐含 `permission`、给了 `field` 隐含 `field`（服务端会拒绝矛盾组合）。
+     */
+    kind?: "permission" | "field";
+    role?: string;
+    resource?: string;
+    /** 只对 permission 轨迹有意义。不能与 `field` 同时给。 */
+    action?: string;
+    /** 只对 field 轨迹有意义。不能与 `action` 同时给。 */
+    field?: string;
+    /** keyset 游标（排他上界）：上一页响应的 `nextPermissionRevisionNo`，原样回传。 */
+    beforePermissionRevisionNo?: number;
+    /** keyset 游标（排他上界）：上一页响应的 `nextFieldRevisionNo`，原样回传。 */
+    beforeFieldRevisionNo?: number;
+    /** 1–500，服务端默认 50。 */
+    limit?: number;
+};
+/**
+ * `GET /v1/teams/:teamId/permissions-matrix/revisions` 的响应。
+ *
+ * 🔴 结构真源是 `@social-ops-hub/contracts` 的
+ * `permissionsMatrixRevisionsResponseSchema`。这里**重新声明**而不是 re-export：
+ * SDK 是公开发布包，contracts 是 `private: true` —— 直接引用会生成一份消费者装不上的
+ * `.d.ts`。改契约时**两处一起改**。
+ *
+ * ⚠️ 五个顶层字段全部必填：两个数组恒为数组（`kind=field` 时另一张是**空数组**而不是
+ * 缺字段）、两个游标恒为 `number | null`、`note` 恒在。对新版 API 可以直接用，不必再写
+ * `res.permissionRevisions ?? []` —— 那种防御会把契约违约读成「没有变更记录」，也就是一个
+ * 错误的审计结论。**但**需要兼容尚未升级的旧 Hub 时，运行时防御仍然要留（滚动部署期）。
+ *
+ * ⚠️ 两个 `next*RevisionNo` 是 **continuation token 而不是 has-more 信号**：本页非空
+ * 就一定有值（哪怕已是最后一页），`null` 只代表本页为空。到底判定 = 再请求一次拿到空数组。
+ */
+export type PermissionOverrideRevisionRowDto = {
+    revisionNo: number;
+    /** 开放字符串（历史轨迹：registry 改名/删除后旧行仍要可读），不是 enum。 */
+    role: string;
+    resource: string;
+    action: string;
+    /** 三态：`true` allow / `false` deny / `null` 未设置。 */
+    oldOverrideAllowed: boolean | null;
+    newOverrideAllowed: boolean | null;
+    changeKind: "insert" | "update" | "delete";
+    /** api_key / cli_token 主体天然为 null —— 正常状态，不是「未知用户」。 */
+    actorUserId: string | null;
+    actorKind: string | null;
+    /** 「从哪个团队入口发起」，**不是**「只影响这个团队」：override 存储是全局的。 */
+    contextTeamId: string | null;
+    requestId: string | null;
+    /** null = 早期记录（写路径未设审计 GUC），无法精确重放当时的 effective 权限。 */
+    authzPolicyVersion: string | null;
+    changedAt: string;
+};
+export type FieldVisibilityRevisionRowDto = Omit<PermissionOverrideRevisionRowDto, "action" | "oldOverrideAllowed" | "newOverrideAllowed"> & {
+    field: string;
+    oldOverrideReadable: boolean | null;
+    newOverrideReadable: boolean | null;
+};
+export type PermissionsMatrixRevisionsResponseDto = {
+    permissionRevisions: PermissionOverrideRevisionRowDto[];
+    fieldRevisions: FieldVisibilityRevisionRowDto[];
+    nextPermissionRevisionNo: number | null;
+    nextFieldRevisionNo: number | null;
+    /** 口径提示：轨迹记的是 override 存储值，不是 effective 权限。 */
+    note: string;
+};
 export type ListAccountGraphParams = {
     limit?: number;
     cursor?: string;
@@ -700,6 +769,7 @@ export declare class SocialHubClient {
         imported: number;
         updated: number;
         skipped: number;
+        conflicted?: number;
     }>;
     listScheduledJobs(teamId: string, params?: ListScheduledJobsParams): Promise<{
         items: unknown[];
@@ -1087,6 +1157,31 @@ export declare class SocialHubClient {
         items: unknown[];
     }>;
     getPermissionsMatrix(teamId: string): Promise<unknown>;
+    /**
+     * 权限 **override** 变更轨迹（迁移 0128）。
+     *
+     * 记录的是**谁在何时插入 / 修改 / 删除了哪一条**权限或字段可见性 override ——
+     * 不只是「deny 改成 allow」，收紧与删除同样留痕。
+     *
+     * 🔴 gate 是 `permissionMatrix:**update**`（不是 `read`）：能看见「谁改了权限」
+     * 本身就是治理信息，还会露出 actor user id。
+     *
+     * ⚠️ 口径：记录的是 **override 存储值**的变更，**不是 effective 权限**的变更
+     * （effective = 静态 authz 矩阵 ⊕ override ⊕ 硬钳制）。`authzPolicyVersion` 是为了
+     * 重放时能用**当时**的规则解释**当时**的 override。
+     * ⚠️ 它**可能为 null**：只有经标准应用写路径（设了审计 GUC）产生的行才带版本号，
+     * **未显式设置该 GUC 的** raw DML / psql 直插留下的行没有 —— 那些行只能看出 override 变了什么，
+     * **无法**可靠还原当时的 effective 权限。
+     *
+     * 翻页是 keyset：把响应里的 `nextPermissionRevisionNo` / `nextFieldRevisionNo`
+     * **原样**回传成下一次的 `beforePermissionRevisionNo` / `beforeFieldRevisionNo`。
+     * 它们是 continuation token 而不是 has-more 信号：本页非空就一定有值，要再请求一次
+     * 拿到空数组才算到底。
+     *
+     * ⚠️ 服务端对互斥组合是 **400 而不是空结果**：`action` 只属于 permission 轨迹、
+     * `field` 只属于 field 轨迹，同时给两个、或给了与 `kind` 矛盾的游标都会被拒。
+     */
+    listPermissionsMatrixRevisions(teamId: string, params?: PermissionsMatrixRevisionsParams): Promise<PermissionsMatrixRevisionsResponseDto>;
     listAccountGraphEdges(teamId: string, params?: ListAccountGraphParams): Promise<{
         items: unknown[];
         nextCursor?: string;
@@ -1972,12 +2067,27 @@ export declare class SocialHubClient {
         items: unknown[];
         total?: number;
     }>;
+    /**
+     * 行业池目录（catalog）。**表本身是系统级共享数据**：`(industryKey, subreddit)` 全局唯一，
+     * 行上的 `teamId` 只是建行时写下的**不可变历史归因署名**，不是隔离边界。
+     *
+     * ⚠️ 因此默认列表是一个 **attribution-scoped view**：只列出当前 team 署名的行。
+     * 想跨团队看（例如提交前查重「这个板块是不是已经有人录过了」）必须给
+     * `aggregateVisibleTeams: true` —— 否则会漏掉别的团队署名的同名行，
+     * 提交后被系统级 upsert 静默更新掉那一行。
+     *
+     * ⚠️ `aggregateVisibleTeams` 在这里同样退化成**署名过滤器**，且范围是**当前主体可见的团队**，
+     * 不是无条件全表：不可见团队署名的行仍然看不到。它与「真团队隔离资源」上的同名参数
+     * （那里是数据边界）语义不同，别照搬理解。
+     */
     listSubredditPoolsCatalog(teamId: string, params?: {
         limit?: number;
         offset?: number;
         status?: string;
         industryKey?: string;
         poolKind?: string;
+        /** 跨**可见团队**的署名聚合视图（不是无条件全表）。 */
+        aggregateVisibleTeams?: boolean;
     }): Promise<{
         items: unknown[];
         total: number;
@@ -2014,11 +2124,18 @@ export declare class SocialHubClient {
         id: string;
         deleted: boolean;
     }>;
+    /**
+     * S0–S3 准入规则。与 catalog 同款：**系统级共享**（`subreddit` 全局唯一），
+     * 行上的 `teamId` 只是历史归因署名。默认列表按署名过滤，
+     * 跨团队查重必须 `aggregateVisibleTeams: true`（范围 = 当前主体可见的团队）。
+     */
     listSubredditPoolTierRules(teamId: string, params?: {
         limit?: number;
         offset?: number;
         tier?: string;
         enabled?: boolean;
+        /** 跨**可见团队**的署名聚合视图（不是无条件全表）。 */
+        aggregateVisibleTeams?: boolean;
     }): Promise<{
         items: unknown[];
         total: number;
@@ -2305,16 +2422,102 @@ export declare class SocialHubClient {
         subscriptionId: string;
         cursorSeq: string;
     }>;
-    /** GET .../notification-events —— 运维列表（**元数据摘要**，不含 payload）。 */
+    /**
+     * GET .../notification-events —— **运维查看面**（元数据摘要，不含 payload）。
+     *
+     * ⚠️ 这不是订阅消费面：它没有 watermark / receipt、不推进任何游标，因此可以自由
+     * 倒序与跳页。要不漏地消费事件请走 {@link SocialOpsHubClient.pullNotificationEvents}。
+     *
+     * 边界语义（服务端冻结）：
+     *   - `afterSeq` 排他**下界**、`beforeSeq` 排他**上界**；
+     *   - `order` **只**决定从区间的哪一端取 N 条与返回顺序，不改变上下界含义；
+     *   - 默认 `order: "desc"` = 最近 N 条；
+     *   - `afterSeq >= beforeSeq` → 400（矛盾区间恒为空，静默返回空会伪装成「没有更多了」）。
+     *
+     * 翻页写法：`order: "desc"` 首屏 → 下一页传 `beforeSeq = 上一页 page.lastSeq`。
+     */
     listNotificationEvents(teamId: string, params?: {
         afterSeq?: string;
+        beforeSeq?: string;
+        order?: "asc" | "desc";
         sourceId?: string;
         limit?: number;
     }): Promise<{
         items: NotificationEventSummaryDto[];
+        /** 本页首尾 seq —— **不是** stream 的 latest/earliest。 */
+        page: {
+            order: "asc" | "desc";
+            firstSeq: string | null;
+            lastSeq: string | null;
+        };
         latestSeq: string;
         earliestAvailableSeq: string;
     }>;
+    /**
+     * 节点 schedule 的**运维可观测面** —— `notification_node_schedules` 的读取端点。
+     *
+     * 🔴 为什么不能从事件流反推：**kill switch 期间的 `missed` 与锚点消失的 `cancelled`
+     * 根本不产生任何事件**。靠事件流反推只会把它们算成 0，于是「今晚一条都没发」
+     * 与「今晚本来就没有到期节点」在页面上长得一模一样。
+     *
+     * ⚠️ 时间窗**必须有界**（服务端默认最近 30 天、上限 90 天）。窗口上限只限制**跨度**，
+     * 不限制窗口必须在最近 90 天内 —— 查更早的窗口完全合法，但可能已经在保留期之外，
+     * 因此 summary / list 都随响应回 `retention`（见 {@link NotificationScheduleRetentionDto}）。
+     */
+    private schedulesBase;
+    /** GET .../notification-node-schedules/summary —— 按 source × status 聚合计数。 */
+    getNotificationNodeSchedulesSummary(teamId: string, params?: {
+        sourceId?: string;
+        dueFrom?: string;
+        dueTo?: string;
+    }): Promise<NotificationNodeSchedulesSummaryDto>;
+    /**
+     * GET .../notification-node-schedules —— 按 source / status / dueAt 窗口列表。
+     *
+     * 分页是 **keyset**（`nextCursor` 为 opaque 串，原样回传即可）；`nextCursor = null`
+     * 表示没有下一页。⚠️ 弱一致：并发 backfill 可能插入更早 `dueAt` 的新行。
+     */
+    listNotificationNodeSchedules(teamId: string, params?: {
+        sourceId?: string;
+        status?: NotificationScheduleStatusDto;
+        subjectId?: string;
+        dueFrom?: string;
+        dueTo?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: NotificationNodeScheduleSummaryDto[];
+        window: {
+            dueFrom: string;
+            dueTo: string;
+        };
+        nextCursor: string | null;
+        retention: NotificationScheduleRetentionDto;
+    }>;
+    /**
+     * GET .../notification-node-schedules/:scheduleId —— 单条状态原因与关联事件 seq。
+     *
+     * ⚠️ **没有** `lastError` 原文：那是任意异常字符串（可能含 SQL / 内部路径）。
+     * 可分支的原因在 `failureReason`（归一化枚举）与 `cancelReason`；
+     * `hasLastError` 只说明「存在原始异常」，原文在服务端日志里。
+     */
+    getNotificationNodeSchedule(teamId: string, scheduleId: string): Promise<NotificationNodeScheduleDetailDto>;
+    /**
+     * GET /v1/settings/notification-schedule-purge-cron/status —— schedule 保留期 GC 的
+     * cron 运行状态。
+     *
+     * 🔴 **系统级、不带 teamId**：状态是 worker 写的全局单 key，不是某个 team 的清理进度。
+     * 权限 `systemSetting:read`（仅 admin/manager）—— 响应带 `workerId` 与异常原文摘要。
+     *
+     * 🔴 **`null` ≠ `0`**：计数为 `null` 表示这次快照没有这个读数（从没跑过 / 只 registered /
+     * failed 未产出），为 `0` 才是「跑了且真的是零」。判「跑没跑过」看
+     * `hasRunSinceRegistration`，别拿 `deleted ?? 0` 糊。
+     *
+     * ⚠️ 三个**非错误**字段：`protectedGroups`（sentinel 不变量有意保护）、
+     * `lockBusyGroups`（被物化/dispatcher 持锁，下轮重试）、`backlog`（独立 `LIMIT 1` probe
+     * 判定的「确实还有候选」）。只有 `failedGroups > 0` 与 `status === "failed"` 是真异常。
+     */
+    getNotificationSchedulePurgeCronStatus(): Promise<NotificationSchedulePurgeCronStatusDto>;
     /** GET .../notification-events/:seq —— 单条完整 envelope（按事件行冻结的权限重验）。 */
     getNotificationEventBySeq(teamId: string, seq: string): Promise<NotificationEventEnvelopeDto>;
     /** GET .../notification-sources —— registry 声明 + 本 team 的 active config 摘要。 */
@@ -2340,8 +2543,23 @@ export declare class SocialHubClient {
     createNotificationSourceConfig(teamId: string, sourceId: string, body: UpsertNotificationSourceConfigSdkBody, params?: {
         activate?: boolean;
     }): Promise<NotificationSourceConfigDto>;
-    /** POST .../notification-sources/:sourceId/configs/:configId/activate。 */
-    activateNotificationSourceConfig(teamId: string, sourceId: string, configId: string): Promise<NotificationSourceConfigDto>;
+    /**
+     * POST .../notification-sources/:sourceId/configs/:configId/activate。
+     *
+     * `expectedActive` 是**可选的 compare-and-set**：
+     *   - 省略 = 保持历史的 last-serialized-writer-wins（两个管理员会互相静默覆盖）；
+     *   - `null` = 「我认为当前没有 active」；
+     *   - `{ configId, version? }` = 「我认为当前 active 就是这一行」。
+     *
+     * 不符 → **409 `SOURCE_CONFIG_ACTIVE_STATE_CONFLICT`**，`details` 带真实的
+     * `actualActiveConfigId` / `actualActiveVersion`，无需再 GET 一次即可重试。
+     *
+     * 🔴 人工写路径（CLI / 后台页）**应当总是带上它** —— 服务端无法替调用方判断
+     * 「你有没有看过当前状态」。
+     */
+    activateNotificationSourceConfig(teamId: string, sourceId: string, configId: string, body?: {
+        expectedActive?: NotificationExpectedActiveDto;
+    }): Promise<NotificationSourceConfigDto>;
     /**
      * PUT .../notification-sources/:sourceId/enabled —— 实时 kill switch。
      *
@@ -2355,6 +2573,49 @@ export declare class SocialHubClient {
         updatedVersions: number;
         enabled: boolean;
     }>;
+    private templatesBase;
+    /** GET /v1/system/notification-source-templates —— 每个已发版 source 的当前 active 模板。 */
+    listNotificationSourceTemplates(): Promise<{
+        items: {
+            sourceId: string;
+            canonicalTopic: string;
+            sourceDefinitionVersion: number;
+            payloadSchemaVersion: string;
+            activeTemplate: NotificationSourceTemplateDto | null;
+        }[];
+    }>;
+    /** GET .../templates —— 该 source 的模板版本历史（version 降序）。 */
+    listNotificationSourceTemplateVersions(sourceId: string, params?: {
+        limit?: number;
+    }): Promise<{
+        items: NotificationSourceTemplateDto[];
+    }>;
+    /** GET .../templates/:id（裸模板行）。 */
+    getNotificationSourceTemplate(sourceId: string, templateId: string): Promise<NotificationSourceTemplateDto>;
+    /**
+     * POST .../templates —— 创建新的不可变模板 version（201）。
+     *
+     * ⚠️ `activate` **默认 false**（与 team config 的 create 相反）：已开启 auto-derivation 的
+     * identity 创建新版本会继承 `true`，若再默认立即激活，一次「存个草稿」就当场改掉了
+     * 全局派生模板。
+     */
+    createNotificationSourceTemplate(sourceId: string, body: UpsertNotificationSourceTemplateSdkBody, params?: {
+        activate?: boolean;
+    }): Promise<NotificationSourceTemplateDto>;
+    /** POST .../templates/:id/activate —— 激活某个已建版本（仍需总闸才会派生）。 */
+    activateNotificationSourceTemplate(sourceId: string, templateId: string): Promise<NotificationSourceTemplateDto>;
+    /**
+     * PUT .../templates/auto-derivation —— 🔴 **自动派生总闸**（系统 admin only）。
+     *
+     * 打开 = 全体「该 source 一条 config 都没有」的 team 在下一次帖子物化 / backfill /
+     * **建订阅**时各自派生出一条 team config，其已发布帖随即开始产生节点事件。
+     * 按 identity 改**全部** version 行（rollout 状态是 identity 级共享状态）。
+     */
+    setNotificationSourceTemplateAutoDerivation(sourceId: string, autoDerivationEnabled: boolean): Promise<{
+        totalVersions: number;
+        updatedVersions: number;
+        autoDerivationEnabled: boolean;
+    }>;
 }
 export type NotificationSubscriptionStatus = "active" | "paused"
 /** 游标落后于保留 floor,已无法保证不漏；需人工确认后 reset。 */
@@ -2446,6 +2707,179 @@ export type UpsertNotificationSourceConfigSdkBody = {
     displayName: string;
     /** 展示用,**不参与**路由/过滤/去重。 */
     displayTopicLabel?: string | null;
+    /**
+     * 创建即激活(`activate` 默认 true)时的 CAS 期望值 —— 与独立 activate 端点同语义。
+     * 🔴 少了它,「新建一个版本并激活」就是绕过 CAS 的后门。
+     * `activate: false` 时带它会 400(矛盾请求)。
+     */
+    expectedActive?: NotificationExpectedActiveDto;
+};
+/**
+ * 激活的 compare-and-set 期望值。
+ *   - 字段缺省 = 不启用 CAS(last-serialized-writer-wins);
+ *   - `null` = 「我认为当前没有 active」;
+ *   - 对象 = 「我认为当前 active 就是这一行」(`version` 给了就一起校验)。
+ *
+ * ⚠️ 刻意是**一个不可自相矛盾的对象**而不是两个平行字段:
+ * 「只校验其中一个、静默忽略另一个」正是 CAS 最典型的失效方式。
+ */
+export type NotificationExpectedActiveDto = null | {
+    configId: string;
+    version?: number;
+};
+export type NotificationScheduleStatusDto = "scheduled" | "emitted" | "missed" | "cancelled" | "superseded";
+export type NotificationNodeScheduleStatusCountsDto = {
+    scheduled: number;
+    emitted: number;
+    missed: number;
+    cancelled: number;
+    superseded: number;
+};
+/**
+ * 该状态在请求窗口内的**完整性** —— 空结果的解释权全在这里。
+ *
+ * - `full`：窗口整体在保证保留期内，**没有就是真的没有**；
+ * - `partial`：窗口横跨保留 floor，更早的部分**可能**已被清理；
+ * - `outside`：窗口整体早于 floor，看到的行只是每组永久保留的 sentinel 残留，
+ *   **不能**当作完整历史。
+ */
+export type NotificationScheduleWindowCompletenessDto = "full" | "partial" | "outside";
+/**
+ * schedule 的保留期披露。
+ *
+ * `notification_node_schedules` 按状态分档清理：`emitted` / `superseded` 180 天、
+ * `missed` / `cancelled` 730 天（判据是 `dueAt`）；`scheduled` 永不删。
+ * ⚠️ `guaranteedRetainedFrom` 是**保证**保留到的最早 `dueAt`，不是「实际最老行」——
+ * GC 落后、批预算用完、每组永久 sentinel 都会让更老的行继续存在。
+ */
+export type NotificationScheduleRetentionDto = {
+    policy: {
+        scheduled: {
+            mode: "indefinite";
+            retentionDays: null;
+            guaranteedRetainedFrom: null;
+        };
+    } & Record<"emitted" | "superseded" | "missed" | "cancelled", {
+        mode: "bounded";
+        retentionDays: number;
+        guaranteedRetainedFrom: string;
+    }>;
+    completenessByStatus: Record<NotificationScheduleStatusDto, NotificationScheduleWindowCompletenessDto>;
+    /** 仅在请求带 `status` 过滤时给出；不带过滤时为 null（五种状态 floor 不同，压不成标量）。 */
+    windowCompleteness: NotificationScheduleWindowCompletenessDto | null;
+};
+export type NotificationNodeSchedulesSummaryDto = {
+    /** 服务端补齐后的实际时间窗(`dueFrom` 含、`dueTo` 不含)。 */
+    window: {
+        dueFrom: string;
+        dueTo: string;
+    };
+    items: {
+        sourceId: string;
+        counts: NotificationNodeScheduleStatusCountsDto;
+        total: number;
+    }[];
+    totals: NotificationNodeScheduleStatusCountsDto;
+    /** 🔴 `missed: 0` 到底是「没异常」还是「已过保留期」，只能靠它区分。 */
+    retention: NotificationScheduleRetentionDto;
+};
+/**
+ * `notification_node_schedules` 保留期 GC cron 的运行状态
+ * （`GET /v1/settings/notification-schedule-purge-cron/status`）。
+ *
+ * 🔴 **每个计数都可能是 `null`，而 `null` ≠ `0`**：`null` = 这次快照没有这个读数，
+ * `0` = 真的跑了且是零。前端空态措辞只能依据 `hasRunSinceRegistration` + `status`。
+ */
+export type NotificationSchedulePurgeCronStatusDto = {
+    /** API 侧 env 回退值。⚠️ 不权威 —— worker 只认自己进程的环境变量。 */
+    schedule: string;
+    /**
+     * 推算 `nextRunAt` 时实际用到的表达式 = `registeredCron ?? schedule`。
+     * ⚠️ **不证明 worker 还活着**（没有 heartbeat），`nextRunAt` 因此是推算值。
+     */
+    effectiveCron: string;
+    /** 按 `effectiveCron` **推算**的下一次触发；表达式非法时为 null。 */
+    nextRunAt: string | null;
+    /**
+     * 🔴 「跑过没有」的唯一判据（`runId !== null`）。
+     * ⚠️ 是「**自本次 worker 注册以来**」——worker 重启会把运行字段清回 null。
+     */
+    hasRunSinceRegistration: boolean;
+    registeredCron: string | null;
+    registeredAt: string | null;
+    runId: string | null;
+    /** `HOSTNAME#pid`：多实例下判断 success/failed 是否同一次运行。 */
+    workerId: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    /** ⚠️ `null` = **没有可读的状态快照**（可能没起过，也可能状态写失败/被清/坏了）。 */
+    status: "registered" | "running" | "success" | "failed" | null;
+    durationMs: number | null;
+    /** 逐档删除数（状态档 → 行数）；`{}` = 没有任何一档删到东西。 */
+    deletedByTier: Record<string, number>;
+    deleted: number | null;
+    groupsPurged: number | null;
+    /** ⚠️ **不是错误**：被 sentinel / `has_scheduled` 不变量有意保护、本轮跳过的组。 */
+    protectedGroups: number | null;
+    /** ⚠️ **不是错误**：锁被物化/dispatcher 占着，下一轮自然重试。 */
+    lockBusyGroups: number | null;
+    /** 🔴 唯一的组级真异常信号。 */
+    failedGroups: number | null;
+    /** 撞到单次删除预算上限（容量信号，不是错误）。 */
+    budgetExhausted: boolean | null;
+    /** 🔴 独立 `LIMIT 1` probe 判定：`true` = **确实还有**候选，不是「可能还有」。 */
+    backlog: boolean | null;
+    lastError: string | null;
+};
+/**
+ * schedule 的归一化失败原因。
+ *
+ * ⚠️ `processing_error` **不代表终态**:记账只 bump attempts,绝不按次数判死,
+ * 所以它会出现在仍会重试的 `scheduled` 行上。要判终态看 `status`。
+ */
+export type NotificationScheduleFailureReasonDto = "kill_switch" | "max_lateness_exceeded" | "processing_error";
+/** `GET .../notification-node-schedules` 的行(**不含 payload、不含 lastError 原文**)。 */
+export type NotificationNodeScheduleSummaryDto = {
+    id: string;
+    teamId: string;
+    sourceId: string;
+    subjectType: string;
+    subjectId: string;
+    sourceConfigVersion: number;
+    policyVersion: string;
+    nodeKey: string;
+    offsetSeconds: number;
+    maxLatenessSeconds: number;
+    status: NotificationScheduleStatusDto;
+    anchorAt: string;
+    dueAt: string;
+    emittedAt: string | null;
+    attempts: number;
+    failureReason: NotificationScheduleFailureReasonDto | null;
+    cancelReason: string | null;
+    brandId: string | null;
+    socialAccountId: string | null;
+    subreddit: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * 单条详情。
+ *
+ * ⚠️ `status = "emitted"` 且 `eventId = null` 是**合法历史状态**:事件过 tombstone 期后
+ * 整行删除,FK 的 `ON DELETE SET NULL` 会清掉 `event_id`。别当数据损坏。
+ */
+export type NotificationNodeScheduleDetailDto = NotificationNodeScheduleSummaryDto & {
+    sourceDefinitionVersion: number;
+    sourceConfigVersionId: string;
+    fieldSetVersion: string;
+    retentionDays: number;
+    eventId: string | null;
+    /** 关联事件的 seq(十进制串,**绝不 Number 化**);事件已清理或从未发射时为 null。 */
+    eventSeq: string | null;
+    supersededByScheduleId: string | null;
+    /** 是否存在原始异常文本(原文不出网)。 */
+    hasLastError: boolean;
 };
 export type NotificationSourceConfigDto = {
     id: string;
@@ -2472,6 +2906,56 @@ export type NotificationSourceConfigDto = {
     configuredFields?: string[];
     /** registry 推导的字段级 authz 并集（AND 语义），只读。 */
     requiredPermissions?: string[];
+    /**
+     * provenance（迁移 0127）：`"template"` = 系统从模板派生，`"manual"` = 人工建的。
+     * 派生行**就是**真正的 team config（events / schedules 的组合租户外键指着它）。
+     */
+    origin?: "manual" | "template";
+    templateId?: string | null;
+    templateVersion?: number | null;
+};
+/**
+ * 系统级 source 模板（迁移 0127）。**没有 teamId** —— 它是一份系统级默认档位 + 字段集，
+ * team 首次需要时派生出一条真正的 team config 行。
+ *
+ * 🔴 `autoDerivationEnabled` **不是** kill switch：它只控制「还要不要给**新** team
+ * bootstrap」，对已派生出来的 config 完全无效（那要用 team config 的 `enabled`）。
+ */
+export type NotificationSourceTemplateDto = {
+    id: string;
+    sourceId: string;
+    version: number;
+    isActive: boolean;
+    autoDerivationEnabled: boolean;
+    nodes: NotificationNodeSpecDto[];
+    filters: NotificationFiltersDto;
+    selectedFields: string[];
+    /** 创建时的 registry 快照，**仅供展示/审计**：派生时用当时的 registry 重算。 */
+    configuredFields: string[];
+    fieldSetVersion: string;
+    requiredPermissions: string[];
+    retentionDays: number;
+    displayName: string;
+    displayTopicLabel: string | null;
+    /** 与当前 registry **不完全相等**时派生会跳过（template_registry_mismatch）。 */
+    sourceDefinitionVersion: number;
+    payloadSchemaVersion: string;
+    activatedAt: string | null;
+    supersededAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/** 创建模板新版本的写 body（镜像 `upsertNotificationSourceTemplateBodySchema`）。 */
+export type UpsertNotificationSourceTemplateSdkBody = {
+    /** 必须与路径上的 sourceId 一致，否则 400。 */
+    sourceId: string;
+    nodes: NotificationNodeSpecDto[];
+    filters?: NotificationFiltersDto;
+    /** 只能是 registry `optionalFields` 的子集，ASCII 升序去重。 */
+    selectedFields?: string[];
+    retentionDays?: number;
+    displayName: string;
+    displayTopicLabel?: string | null;
 };
 /**
  * 事件信封。四层版本 + `includedFields` 决定形状,消费方按 `payloadSchemaVersion` 分支;