@sema-agent/server 7.29.0 → 7.30.0

package/dist/plugins/store-backend.d.ts

@@ -25,6 +25,8 @@ import type { CounterDegradeHook } from "./write-behind-counter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { type SqlSharedMemoryStore, type SharedMemoryScopeAuthorizer } from "./shared-memory-store-sql.js";
 import { type AdoptionLogStore } from "./adoption-log-sql.js";
+import { type SqlRetentionStore, type SqlRetentionStoreOptions } from "./retention-store-sql.js";
+import { type RetentionLaneStore } from "./retention-lane-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
 /** E18 resume-at eventId→entryId anchor map — tidb/pg/local 3-backend (works LOCAL; needs only the session tree +
@@ -207,6 +209,24 @@ export interface StoreBackend {
      * 缺席 ⇒ endpoint 落到显式的单副本内存降级臂(见 `leader/endpoint.ts` 的 store 缺席注)。
      */
     leaderRun?(): LeaderRunStore;
+    /**
+     * #270 —— 托管留存的**破坏性**三方法(core `ManagedRetentionCapability` 的 server 侧真身)。
+     * **SQL 后端专有**,`local` 刻意省略:那三条腿是跨十余张表的单事务级联,file/in-memory 形没有事务面
+     * 也没有那些表,所以它诚实声明 `retention:"none"`(见 `local-session-store.ts` 的同款注)。
+     *
+     * `taskAttachmentTable` 必填、无默认值 —— boot 只在配了对象存储时才 ensure 那张表,一条盲发的
+     * DELETE 在无 MinIO 的部署上会以 unknown-table 打红整轮 sweep(理由逐字见
+     * `retention-store-sql.ts` 的 `SqlRetentionStoreOptions`)。
+     */
+    retention?(opts: SqlRetentionStoreOptions): SqlRetentionStore;
+    /**
+     * #270 车2 —— 留存执行面的**非破坏性**半场:sweep 租约、legal-hold 的放置/解除、审计表的读与
+     * 非破坏行的写。同样 SQL 专有(它写的三张表只在 SQL schema 里)。
+     *
+     * 🔴 与上一格**分家**是有意的:拿到本对象的消费方(operator 路由)结构上删不掉任何业务数据。
+     * 两面合并会让「拿到这只店 = 能删」这条读法失真。
+     */
+    retentionLane?(): RetentionLaneStore;
     breaker?(onWriteFail?: (streak: number) => void): BreakerStateStore;
     costQuota?(limitMicroUsd: number, windowMs: number, onDegraded?: CounterDegradeHook): CostQuotaStore;
     rateLimiter?(limit: number, onDegraded?: CounterDegradeHook): RateLimiterStore;

package/dist/plugins/store-backend.js

@@ -43,6 +43,9 @@ import { TiDBSessionStore } from "./tidb-session-store.js";
 import { PgSessionStore } from "./pg-session-storage.js";
 import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
 import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
+// #270:托管留存的两半场(破坏性三方法 = 车1;租约/hold/审计 = 车2)。SQL 后端专有,local 诚实缺席。
+import { TiDBRetentionStore, PgRetentionStore } from "./retention-store-sql.js";
+import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
 // #154 车二:持久化权限规则店(三面一束)。`mysqlDriver`/`pgDriver` 是既有的方言中立 seam。
 // #203 §1:local 车道的 File 三面束(core 现成 provider + 本仓 File 形审批记录/导入票)。
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
@@ -120,6 +123,8 @@ class TiDBBackend {
     imageIndex() { return new TiDBImageIndex(this.pool); }
     imageBake() { return new TiDBImageBake(this.pool); }
     leaderRun() { return new TiDBLeaderRunStore(this.pool); } // #193 车4 件1(无状态 store,每次新建同兄弟)
+    retention(opts) { return new TiDBRetentionStore(this.pool, opts); } // #270 车1(破坏性三方法)
+    retentionLane() { return new TiDBRetentionLaneStore(this.pool); } // #270 车2(租约/hold/审计,删不了业务数据)
     breaker(onWriteFail) { return new TiDBBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
@@ -158,6 +163,8 @@ class PgBackend {
     imageIndex() { return new PgImageIndex(this.pool); }
     imageBake() { return new PgImageBake(this.pool); }
     leaderRun() { return new PgLeaderRunStore(this.pool); } // #193 车4 件1(SQL twin)
+    retention(opts) { return new PgRetentionStore(this.pool, opts); } // #270 车1(SQL twin)
+    retentionLane() { return new PgRetentionLaneStore(this.pool); } // #270 车2(SQL twin)
     breaker(onWriteFail) { return new PgBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }

package/dist/plugins/tidb-pool.js

@@ -3,6 +3,7 @@ import { TIDB_APPROVAL_ASK_STATEMENTS } from "./approval-ask-store-sql.js";
 import { TIDB_LEADER_RUN_STATEMENTS } from "./leader-run-store-sql.js";
 import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
+import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
 /**
  * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
  * Owned by `main.ts`; closed on shutdown.
@@ -715,6 +716,10 @@ export const SCHEMA_STATEMENTS = [
     // permission-rule-store-sql.ts 的 `TIDB_PERMISSION_RULE_STATEMENTS`(与 PG twin 并排);展开进这个
     // 数组的理由与上面那族逐字相同(named-lock 的那条 conn + 「这张表算生产 schema」的声明)。
     ...TIDB_PERMISSION_RULE_STATEMENTS,
+    // #270 车1(托管留存执行面)的四张表:审计(§6)/ hold(§5)/ sweep 租约(§3)/ 墓碑(§2)。真源 =
+    // retention-store-sql.ts 的 `TIDB_RETENTION_STATEMENTS`(与 PG twin 并排);展开进这个数组的理由与
+    // 上面那几族逐字相同(named-lock 的那条 conn + 「这张表算生产 schema」的声明)。
+    ...TIDB_RETENTION_STATEMENTS,
 ];
 /** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";

package/dist/plugins/tidb-session-store.d.ts

@@ -16,6 +16,9 @@ import type { SessionSummary } from "./store-contracts.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class TiDBSessionStore implements SessionStore {
     private readonly pool;
+    /** #270 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而实现体在别处」逐字见
+     *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    readonly retention: import("@sema-agent/core").RetentionDeclaration;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
     constructor(pool: Pool);

package/dist/plugins/tidb-session-store.js

@@ -14,11 +14,15 @@
 import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./tidb-session-storage.js";
 import { escapeLike } from "./sql-escape.js";
+import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, // 两孪生店同源(理由见 kernel 处顶注:同值双抄单边改值 ⇒ 两后端 GC 判定分家)
  } from "../session-sync-kernel.js";
 export class TiDBSessionStore {
     pool;
+    /** #270 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而实现体在别处」逐字见
+     *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    retention = MANAGED_RETENTION;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {

package/dist/plugins/tool-result-store-sql.d.ts

@@ -26,6 +26,9 @@ export declare function assertToolResultProvenanceSchema(query: (sql: string) =>
 /** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
+    /** #270 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
+     *  逐字见 {@link MANAGED_RETENTION}(本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
+    readonly retention: import("@sema-agent/core").RetentionDeclaration;
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;

package/dist/plugins/tool-result-store-sql.js

@@ -38,6 +38,7 @@
 import { MAX_MINTED_TOOL_RESULT_REF_CHARS, assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance } from "@sema-agent/core";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { MANAGED_RETENTION } from "./retention-store-sql.js";
 /** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
  *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
  *  tables, so a self-contained ensureSchema is safe (central pg-pool aggregation is done separately). */
@@ -105,6 +106,9 @@ export async function assertToolResultProvenanceSchema(query, dialect) {
 /** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export class SqlToolResultStore {
     db;
+    /** #270 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
+     *  逐字见 {@link MANAGED_RETENTION}(本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
+    retention = MANAGED_RETENTION;
     constructor(db) {
         this.db = db;
     }

package/dist/run-local.js

@@ -73,6 +73,7 @@ import { createMemorySyncRunner, createMemorySyncTransport } from "./memory-sync
 import { buildPricing, cappedCeiling, createTracer } from "./budget.js";
 import { createSharedRunnerDeps } from "./boot/runner-deps.js";
 import { createGovernanceSeams } from "./boot/governance-seams.js";
+import { assertRetentionLaneWirable } from "./boot/retention-lane.js"; // #270 车2:lane 自持门(本地形恒无执行器)
 import { createOrgMemoryAdmissionWiring } from "./boot/org-memory.js";
 import { createPermissionDeniedMeter } from "./observability/tool-trace.js";
 import { createKeyResolver } from "./key-resolver.js";
@@ -607,6 +608,21 @@ export async function runLocal(argv, deps = {}) {
     // 有:`COMPLIANCE_PROFILE` / `LOCKED_CONFIG_KEYS` / `RETENTION_MAX_AGE_DAYS` 是从同一份本地 `.env` 读出来
     // 的,一个写下了档位的用户在 `sema` 与本机 HTTP 服务上必须得到同一个答案(两条腿对同一份配置两套行为
     // 正是本仓在册的病族)。三键未配 = 三座席缺席 = 本腿逐字零变化。
+    // #270 车2:lane 自持门在本地形也要跑,理由与上一段逐字相同 —— `RETENTION_SWEEP_INTERVAL_SEC>0`
+    // 是从同一份 `.env` 读出来的,而本地形**结构上**没有执行器(file 店三方法不存在,诚实声明 "none")。
+    // 少了这道门,一个写下了那根旋钮的用户会在 `sema` 上得到一台自称有留存治理、其实什么都不删的机器,
+    // 而在 HTTP 形上得到一条拒启 —— 两条腿对同一份配置两套行为,正是本仓在册的病族。
+    assertRetentionLaneWirable({
+        intervalSec: config.retentionSweep.intervalSec,
+        policy: config.retentionPolicy,
+        executor: undefined, // 本地形恒无执行器(见上)
+        stores: [
+            { name: "sessionStore", store: sessionStore },
+            { name: "checkpointStore", store: fileBackend.checkpointStore },
+            { name: "toolResultStore", store: fileBackend.toolResultStore },
+        ],
+        locked: (config.lockedConfigKeys ?? []).includes("retentionPolicy"),
+    });
     const governanceSeams = createGovernanceSeams({
         config,
         logger,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.29.0",
+  "version": "7.30.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",