@sema-agent/server 7.37.0 → 7.38.0-rc.2

package/dist/plugins/session-placement.js

@@ -0,0 +1,153 @@
+/**
+ * #292 C18(core 5.48.0 design/323「不造新店」提货批,黑板 [4743] 点名义务)——**subagent 转录持久化**
+ * 的 placement 语义,SQL 孪生共用的一份判据。
+ *
+ * ## 这是什么
+ *
+ * core 5.48.0 给 `SessionStore` 开了一组**全 optional** 的 placement 面:一只**声明** `placements`
+ * (「本店懂 placement 语义,且落在 subagent 分区里的会话是这个耐久度」)+ `acquire(id,{placement})`
+ * 的创建形 + `listPlaced` / `placementOf` 两只读面。声明即承诺**六条义务**(core `SessionStore.placements`
+ * 顶注逐字):
+ *
+ *  1. placed 会话享受所声明的耐久度(重启后 `acquire(id,{requireExisting:true})` 仍到得了);
+ *  2. placed 会话**不上宿主枚举面**(壳的 /resume 列表不许把子代转录当成可续聊会话);
+ *  3. **未** placed 的会话,acquire 语义逐字节不变;
+ *  4. `release(placedId)` 是**真删除**(durable 史一并),联合 reap 的「行与会话同亡」靠它;
+ *  5. placement **first-write 不可变**:re-open(`requireExisting`,带不带 placement 参数)返回同一
+ *     会话且**永不重写**元组;
+ *  6. placed id **不可被 claim**:后来的 claim 形 acquire(无 `requireExisting`、无创建 placement)
+ *     撞上已存在的 placed id ⇒ 响亮拒 `SessionError("placement_refused")`,绝不附着。
+ *
+ * ## 为什么判据住在这里而不是各写一份
+ *
+ * 本仓成文教训(`memory-origin-law.ts` 顶注同族、`key-resolver.ts` 顶注「链只有一条」):两支方言各
+ * 抄一份准入判据,迟早在某一支上少一个分支——而少掉的那一支**没有任何报错面**,表现只是「这台机器上
+ * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名、行→元组的映射都在
+ * 这一处;两支后端只负责在自己的 I/O 点上调用它。
+ *
+ * ## 判据的两个方向(缺一不可,core `TtlSessionStore.assertPlacementAdmission` 的镜像)
+ *
+ * ① **claim 关门**:已 placed 的行拒绝 claim 形 acquire;
+ * ② **镜像方向(pre-claim squat 竞态)**:子会话 id 在 spawn 帧上**先于**子代 prepare 公布,于是一次
+ *    并发的 claim 形 acquire 可能抢先建出**普通**会话,而后带 placement 的可信调用方拿到的就是一只
+ *    宿主可枚举、release 不真删的普通会话 ——「声明了 full tier 却在静默说谎」。⇒ 在**声明了分区**的
+ *    店上,带 placement 的 acquire 必须回读到**已持久化**且同一元组身份的行,回读缺失/异组=响亮拒。
+ */
+import { SessionError } from "@sema-agent/core";
+/**
+ * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`)。
+ *
+ * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
+ * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在
+ * 本店实装之后才允许存在——它是一句关于本店行为的承诺,不是一个功能开关。
+ * `durable` 的依据:两支孪生的会话史落在 `session_meta`+`session_event` 两张真表上,进程重启后
+ * `acquire(id,{requireExisting:true})` 从事件日志重放(义务 1 的机器证在
+ * `test/session-placement-db-integration.test.ts` 的跨进程复活格)。
+ */
+export const SQL_SESSION_PLACEMENTS = { subagent: { durability: "durable" } };
+/**
+ * `session_meta` 上承载 placement 元组的六列,**两方言同名**(单点定义:列名手抄两份必漂,而漂掉的
+ * 那一支只会表现为「这台机器上 placed 行读不出来」——静默,不报错)。
+ * `placed_at` 是 GC 的年龄锚(core `PlacedSessionRow.placedAt`);其余五列是元组本身。
+ */
+export const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
+/** DATETIME/TIMESTAMPTZ 单元格 → epoch ms。两支池都返回 `Date`(mysql2 `timezone:"Z"` / node-pg 原生),
+ *  字符串臂是防御性回落(驱动配置若变,宁可解析一次也不要静默把 placedAt 读成 NaN)。 */
+function toEpochMs(v) {
+    if (v == null)
+        return undefined;
+    if (v instanceof Date)
+        return v.getTime();
+    const ms = new Date(String(v)).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}
+const asStringOrUndefined = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+/**
+ * 行 → 持久化的 placement 元组(`undefined` = 这是一只普通会话)。
+ *
+ * 🔴 判别位是 `placement_kind`:它在场即 placed。`placed_at` 缺失(带外 SQL 写进半只元组)时回落
+ * `0` 而**不是**把整只元组读成缺席——把「元组半缺」读成「没有 placement」等于让义务 2/4/6 在那一行上
+ * 集体失效(宿主枚举会重新列出它、release 退回租约语义);`listPlaced` 那一侧另有 `tupleIncomplete`
+ * 的诚实变体负责让 GC 对它 fail-closed。
+ */
+export function placementFromRow(row) {
+    if (row === undefined)
+        return undefined;
+    const kind = asStringOrUndefined(row.placement_kind);
+    if (kind === undefined)
+        return undefined;
+    return {
+        kind: kind,
+        ...(asStringOrUndefined(row.placement_scope) !== undefined ? { scope: asStringOrUndefined(row.placement_scope) } : {}),
+        ...(asStringOrUndefined(row.placement_parent_session_id) !== undefined ? { parentSessionId: asStringOrUndefined(row.placement_parent_session_id) } : {}),
+        ...(asStringOrUndefined(row.placement_root_session_id) !== undefined ? { rootSessionId: asStringOrUndefined(row.placement_root_session_id) } : {}),
+        ...(asStringOrUndefined(row.placement_handle) !== undefined ? { handle: asStringOrUndefined(row.placement_handle) } : {}),
+        placedAt: toEpochMs(row.placed_at) ?? 0,
+    };
+}
+/**
+ * 行 → 一条 {@link PlacedSessionRow}(`listPlaced` 的行形)。
+ *
+ * core 契约:join 键是**完整**的 `(scope, handle)`;缺任何一半 ⇒ 返回 `tupleIncomplete` 的诚实变体,
+ * 消费方对它 fail-closed(永不按年龄收割)。一个「无行」与「另一个租户有行」分不清的 join 不许删东西。
+ */
+export function placedRowFromRow(sessionId, row, lastActivityMs) {
+    const placedAt = toEpochMs(row.placed_at) ?? lastActivityMs ?? 0;
+    const scope = asStringOrUndefined(row.placement_scope);
+    const handle = asStringOrUndefined(row.placement_handle);
+    return scope !== undefined && handle !== undefined
+        ? { sessionId, placedAt, scope, handle }
+        : { sessionId, placedAt, tupleIncomplete: true };
+}
+/** 创建时一次落行的六个绑定值(顺序 = {@link PLACEMENT_SELECT_COLUMNS});无 placement ⇒ 六个 NULL。 */
+export function placementInsertValues(placement, placedAt) {
+    if (placement === undefined)
+        return [null, null, null, null, null, null];
+    return [
+        placement.kind,
+        placement.scope ?? null,
+        placement.parentSessionId ?? null,
+        placement.rootSessionId ?? null,
+        placement.handle ?? null,
+        placedAt,
+    ];
+}
+/**
+ * 准入判据 —— **两个方向**(顶注 ①②;core `TtlSessionStore.assertPlacementAdmission` 的 SQL 镜像,
+ * 逐条同义,文案自铸)。
+ *
+ * @param persisted 该 id 在库里**已持久化**的元组(缺席 = 普通会话 / 无此行)。
+ *
+ * · 方向①(claim 关门):`persisted` 在场 + 非 `requireExisting` + 调用方没带创建 placement ⇒ 拒。
+ *   `requireExisting`(读/复活形,义务 5)与「创建调用及其幂等重取」(带 placement 的可信内部链)
+ *   是仅有的两个合法形。placement 不可变意味着带 placement 的参数**永远重写不了**任何东西——持久化
+ *   的那一份恒赢,所以放行它不开任何后门。
+ * · 方向②(镜像/squat):带 placement 的创建形回读到**缺席**或**异组**元组 ⇒ 拒。缺席 = 并发的
+ *   claim 形抢先建出了普通会话(或带外写把元组抹了);异组 = 同 id 上坐着另一条委派链的转录。
+ *   两者都不许让「声明了 durable 分区」这句话在静默中变成谎。
+ */
+export function assertPlacementAdmission(sessionId, persisted, opts) {
+    if (opts?.requireExisting === true)
+        return; // 读/复活形:义务 5 的合法入口,两方向都不判
+    if (persisted !== undefined && opts?.placement === undefined) {
+        throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${persisted.kind} placement partition — a claim-form acquire cannot attach to it (read it with requireExisting, or address the agent through its a* handle)`);
+    }
+    if (opts?.placement === undefined)
+        return;
+    const want = opts.placement;
+    if (persisted === undefined) {
+        throw new SessionError("placement_refused", `session ${sessionId} exists OUTSIDE the ${want.kind} placement partition it was declared into — refusing to run a subagent transcript on it (a concurrent claim-form create won this id, or the tuple was written away out of band)`);
+    }
+    if (persisted.kind !== want.kind || persisted.scope !== want.scope || persisted.handle !== want.handle) {
+        throw new SessionError("placement_refused", `session ${sessionId}'s persisted placement does not match the declared one (persisted ${persisted.kind}/${persisted.scope ?? "-"}/${persisted.handle ?? "-"} vs declared ${want.kind}/${want.scope ?? "-"}/${want.handle ?? "-"}) — refusing a cross-tuple attach`);
+    }
+}
+/**
+ * 一次 `listPlaced` 最多带回的行数。
+ *
+ * core 契约不设上界,但两支孪生面对的是一张可以很大的真表:无界 SELECT 会让一次 reap tick 把整个
+ * placed 分区拉进内存。行按**年龄升序**(最老先出)⇒ 截断的语义是「本 tick 先收最老的一批,下一 tick
+ * 接着收」,而不是「有些行永远看不见」。判据消费方(core 的分区收割腿)本就是每 tick 重新枚举的。
+ */
+export const LIST_PLACED_BATCH = 1000;
+//# sourceMappingURL=session-placement.js.map

package/dist/plugins/session-store.js

@@ -57,7 +57,13 @@ export async function ensureSessionDurable(hostStore, sessionId) {
             throw new Error(`session "${sessionId}" exists in the durable store but is empty (no leaf entry) — likely a claim-create shell row, not real durable content`);
     }
     finally {
-        await hostStore.release(acquired.sessionId);
+        // 🔴 #292 C18(core 5.48.0 [4743] 点名义务①,**preflight/探活法**):这是一次「只为验存在」的
+        // acquire ⇒ 收尾必须是 `forget`(丢暖引用),**绝不能**是 `release`。core 5.48 起
+        // `release(placedId)` 被重定义为**真删除**,而本函数正是 park 前的探活腿:一条跨重启 parked 的
+        // 子代转录在这里被 release 一次就等于**删掉转录 + 烧掉那次审批**(core 发车前重扫的 P1 同款撞点,
+        // 四域复现)。缺 `forget` 面 ⇒ 什么都不做(core B-17 判例:绝不代之以 release);两支 SQL 孪生与
+        // 包装店都实装了 forget,所以生产路径上这一步是真的丢引用,不是 no-op。
+        await hostStore.forget?.(acquired.sessionId);
     }
 }
 /**

package/dist/plugins/tidb-cost-quota.d.ts

@@ -5,12 +5,17 @@
  * `maxCostUsd` gate). `scope_key` is opaque (principal today; team/feature later — design/30 N3).
  */
 import type { Pool } from "mysql2/promise";
-import type { QuotaDecision, QuotaTracker } from "../observability/cost-quota.js";
+import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class TiDBCostQuota implements QuotaTracker {
-    private readonly limitMicroUsd;
     private readonly counter;
+    /** #322:限额=比较参数(行里只有花费);窗长换代经 counter.setWindowMs(桶键语义见那里)。 */
+    private limitMicroUsd;
+    private refreshRequested;
+    private refreshIntervalMs;
     constructor(pool: Pool, limitMicroUsd: number, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
+    setLimits(next: QuotaLimits): void;
+    private syncRefresh;
     check(scopeKey: string): QuotaDecision;
     add(scopeKey: string, micro: number): void;
     flush(): Promise<void>;

package/dist/plugins/tidb-cost-quota.js

@@ -1,17 +1,38 @@
 import { WriteBehindCounter } from "./write-behind-counter.js";
 export class TiDBCostQuota {
-    limitMicroUsd;
     counter;
+    /** #322:限额=比较参数(行里只有花费);窗长换代经 counter.setWindowMs(桶键语义见那里)。 */
+    limitMicroUsd;
+    refreshRequested = false;
+    refreshIntervalMs;
     constructor(pool, limitMicroUsd, windowMs, now, onDegraded, queryTimeoutMs) {
         this.limitMicroUsd = limitMicroUsd;
         this.counter = new WriteBehindCounter(pool, { table: "cost_quota", keyCol: "scope_key", valCol: "micro_usd" }, windowMs, now, onDegraded, queryTimeoutMs);
     }
+    setLimits(next) {
+        this.limitMicroUsd = next.limitMicroUsd;
+        this.counter.setWindowMs(next.windowMs);
+        this.syncRefresh();
+    }
+    syncRefresh() {
+        if (!this.refreshRequested)
+            return;
+        if (this.limitMicroUsd > 0)
+            this.counter.startRefresh(this.refreshIntervalMs);
+        else
+            this.counter.stop();
+    }
     check(scopeKey) {
+        // 关断哨兵:零 counter 访问、零 SQL(恒构造的代价必须是 0)。
+        if (this.limitMicroUsd <= 0)
+            return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
         const used = this.counter.used(scopeKey);
         const allowed = used < this.limitMicroUsd;
         return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec: allowed ? 0 : this.counter.retryAfterSec() };
     }
     add(scopeKey, micro) {
+        if (this.limitMicroUsd <= 0)
+            return; // off ⇒ 不攒本地增量(也就没有要 flush 的东西)
         this.counter.addLocal(scopeKey, micro);
     }
     // write-behind lifecycle (delegated; exposed for the reaper/tests)
@@ -25,10 +46,13 @@ export class TiDBCostQuota {
         return this.counter.reap();
     }
     startRefresh(intervalMs) {
-        this.counter.startRefresh(intervalMs);
+        this.refreshRequested = true;
+        this.refreshIntervalMs = intervalMs;
+        this.syncRefresh();
         return this;
     }
     stop() {
+        this.refreshRequested = false;
         this.counter.stop();
     }
 }

package/dist/plugins/tidb-pool.js

@@ -77,8 +77,22 @@ export const SCHEMA_STATEMENTS = [
      -- title: auto-generated session title (cheap-model one-liner at first submit; write-once via
      -- setTitleIfNull — the user-facing RENAME layer lives BFF-side as a label overlay, not here).
      title       VARCHAR(120) NULL,
+     -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组,**创建时一次落行、
+     -- first-write 不可变**(register 的 ON DUPLICATE 臂永不重写这六列)。判别位 = placement_kind:
+     -- 在场 ⇒ 该会话住在 placement 分区里(不上宿主枚举、claim 形 acquire 恒拒、release=真删除、
+     -- 留存视界腿不碰)。scope/handle 是与 background_agent 行的 join 键(两列宽度对齐那张表的
+     -- VARCHAR(190),join 两侧不许一宽一窄);placed_at 是分区 GC 的年龄锚。语义与六条义务的完整
+     -- 读法见 src/plugins/session-placement.ts 顶注。
+     placement_kind              VARCHAR(32)  NULL,
+     placement_scope             VARCHAR(190) NULL,
+     placement_parent_session_id VARCHAR(190) NULL,
+     placement_root_session_id   VARCHAR(190) NULL,
+     placement_handle            VARCHAR(190) NULL,
+     placed_at                   DATETIME(3)  NULL,
      PRIMARY KEY (session_id),
-     KEY idx_session_meta_owner (owner)
+     KEY idx_session_meta_owner (owner),
+     -- listPlaced 的检索腿(kind + 租户 + 年龄升序);普通会话这三列全 NULL ⇒ 不占索引选择性。
+     KEY idx_session_meta_placement (placement_kind, placement_scope, placed_at)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS session_event (
      session_id  VARCHAR(64) NOT NULL,

package/dist/plugins/tidb-rate-limiter.d.ts

@@ -9,12 +9,19 @@
  * write-behind — same trade as the cross-replica circuit breaker and cost quota.
  */
 import type { Pool } from "mysql2/promise";
-import type { RateDecision, RateGate } from "../observability/rate-limit.js";
+import type { RateDecision, RateGate, RateLimits } from "../observability/rate-limit.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class TiDBRateLimiter implements RateGate {
-    private readonly limit;
     private readonly counter;
+    /** 🔴 #322:限额是比较参数、不是行状态(SQL 腿的行里只有计数),所以换代只动它,库里一行都不用碰。 */
+    private limit;
+    /** 装配点表达过的运维意图(「这条腿该有刷新环」)。关断哨兵靠它把环真正停掉/重开 —— 0 态零 SQL。 */
+    private refreshRequested;
+    private refreshIntervalMs;
     constructor(pool: Pool, limit: number, windowMs?: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
+    setLimits(next: RateLimits): void;
+    /** off ⇒ 停环(零 SQL);on 且装配点要过环 ⇒ 起环(幂等,counter 内部 `??=`)。 */
+    private syncRefresh;
     check(key: string): RateDecision;
     /** The flush loop self-reaps old windows; the periodic sweeper has nothing to do for this backend. */
     sweep(): void;

package/dist/plugins/tidb-rate-limiter.js

@@ -1,11 +1,28 @@
 import { WriteBehindCounter } from "./write-behind-counter.js";
 export class TiDBRateLimiter {
-    limit;
     counter;
+    /** 🔴 #322:限额是比较参数、不是行状态(SQL 腿的行里只有计数),所以换代只动它,库里一行都不用碰。 */
+    limit;
+    /** 装配点表达过的运维意图(「这条腿该有刷新环」)。关断哨兵靠它把环真正停掉/重开 —— 0 态零 SQL。 */
+    refreshRequested = false;
+    refreshIntervalMs;
     constructor(pool, limit, windowMs = 60_000, now, onDegraded, queryTimeoutMs) {
         this.limit = limit;
         this.counter = new WriteBehindCounter(pool, { table: "rate_limit", keyCol: "limit_key", valCol: "hits" }, windowMs, now, onDegraded, queryTimeoutMs);
     }
+    setLimits(next) {
+        this.limit = next.rateLimitPerMin;
+        this.syncRefresh();
+    }
+    /** off ⇒ 停环(零 SQL);on 且装配点要过环 ⇒ 起环(幂等,counter 内部 `??=`)。 */
+    syncRefresh() {
+        if (!this.refreshRequested)
+            return;
+        if (this.limit > 0)
+            this.counter.startRefresh(this.refreshIntervalMs);
+        else
+            this.counter.stop();
+    }
     check(key) {
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
@@ -27,10 +44,13 @@ export class TiDBRateLimiter {
         return this.counter.refresh();
     }
     startRefresh(intervalMs) {
-        this.counter.startRefresh(intervalMs);
+        this.refreshRequested = true;
+        this.refreshIntervalMs = intervalMs;
+        this.syncRefresh(); // 关断态下**不起环**:恒构造的代价必须是零 SQL,否则「默认部署」白付一条后台环
         return this;
     }
     stop() {
+        this.refreshRequested = false;
         this.counter.stop();
     }
 }

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

@@ -2,6 +2,7 @@ import { emitLeafAdvance } from "../session-leaf-bus.js";
 import { BaseSessionStorage, SessionError, leafIdAfterEntry, normalizePromptEpoch, } from "@sema-agent/core";
 import { toIso } from "./sql-row-helpers.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
+import { PLACEMENT_SELECT_COLUMNS, placementFromRow } from "./session-placement.js";
 /** 判据属主 = `sql-errors.ts`(A-032 P1-①;旧形只认 `code`,只带 errno 的驱动错误漏判)。 */
 const isDupKey = isMysqlDupKeyError;
 /**
@@ -80,14 +81,21 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         // actors drive the same session concurrently, which the task_active session lock already
         // serializes; the persist path then re-CASes leaf_id/leaf_seq, so a stale wake loses cleanly there. A
         // single-snapshot read would need a repeatable-read txn per wake — not worth it for this guard rail.
-        const [metaRows] = await pool.query("SELECT created_at, leaf_id, leaf_seq FROM session_meta WHERE session_id = ?", [sessionId]);
+        const [metaRows] = await pool.query(
+        // #292 C18:placement 六列**捎带**在这条既有的 meta SELECT 上(不另开一次往返)——准入判据
+        // (claim 关门 / 镜像 squat 判)读的就是这一份持久化元组,而 acquire 的热路径不该为它多付一次 RTT。
+        `SELECT created_at, leaf_id, leaf_seq, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = ?`, [sessionId]);
         const meta = metaRows[0];
         if (!meta)
             return null;
         const { floorEntryId, floorSeq } = await TiDBSessionStorage.computeFloor(pool, sessionId);
         const [eventRows] = await pool.query("SELECT payload FROM session_event WHERE session_id = ? AND seq >= ? ORDER BY seq ASC", [sessionId, floorSeq]);
         const entries = eventRows.map((r) => typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload);
-        const metadata = { id: sessionId, createdAt: toIso(meta.created_at) };
+        // #292 C18:持久化的 placement 元组骑在 core 5.48 的 `SessionMetadata.placement` 可选键上
+        // (普通会话不铸这个键)——于是「这只会话是不是 placed」对每一个拿到 session 的消费方都是**同一份**
+        // 事实,不需要谁再去猜或另查一次。
+        const placement = placementFromRow(meta);
+        const metadata = { id: sessionId, createdAt: toIso(meta.created_at), ...(placement !== undefined ? { placement } : {}) };
         return new TiDBSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, Number(meta.leaf_seq), floorEntryId, floorSeq);
     }
     /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). */

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

@@ -10,24 +10,50 @@
  * Persistence only. **Tenant authorization (who may wake which session) lives in the service layer**
  * (`src/security.ts`), which uses `ownerOf` / `register` below. The store does not infer identity.
  */
-import { type AcquiredSession, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import { type AcquiredSession, type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import type { SessionSummary } from "./store-contracts.js";
+import { type PlacementAcquireOpts } from "./session-placement.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;
+    /** #292 C18(core 5.48.0 design/323):placement **声明**。六条义务的实装点逐条见
+     *  {@link SQL_SESSION_PLACEMENTS} 顶注与本类的 acquire / listSessions / release / listPlaced /
+     *  placementOf 各处的 `#292` 注。 */
+    readonly placements: {
+        readonly subagent: {
+            readonly durability: "durable";
+        };
+    };
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
     constructor(pool: Pool);
-    acquire(sessionId?: string, opts?: {
-        requireExisting?: boolean;
-    }): Promise<AcquiredSession>;
+    acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
-    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten. */
-    register(sessionId: string, owner: string | null): Promise<void>;
+    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
+     *  #292:`placement` 在场时与行同一条 INSERT 落六列;ON DUPLICATE 臂是 no-op ⇒ 已存在的行的元组
+     *  **永不被重写**(first-write 不可变,义务 5 的写侧半场)。 */
+    register(sessionId: string, owner: string | null, placement?: SessionPlacement): Promise<void>;
+    /**
+     * #292 义务 6 的廉价探针 —— 一行 PK SELECT:`undefined` = 普通会话或无此行。
+     * (release 的冷缓存腿、包装店的暖命中准入判、诊断面共用这一只。)
+     */
+    placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
+    /**
+     * #292 义务 5 —— placed 分区的**自有枚举**(联合 reap 的分区腿输入)。
+     *
+     * 年龄锚 = `COALESCE(updated_at, placed_at)`:`updated_at` 是本店的「最后活动」标记(register 时置、
+     * 每次 append/touch 推进),取不到才回落 `placed_at` —— 与 core File 店「mtime 优先、placedAt 回落」
+     * 的读法同义。行按年龄升序、上界 {@link LIST_PLACED_BATCH}(理由见那里)。
+     * join 半缺(scope/handle 任一为 NULL)⇒ `tupleIncomplete` 诚实变体,消费方对它 fail-closed。
+     */
+    listPlaced(kind: "subagent", opts?: {
+        olderThanMs?: number;
+        scope?: string;
+    }): Promise<PlacedSessionRow[]>;
     /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
     touch(sessionId: string): Promise<void>;
@@ -42,8 +68,28 @@ export declare class TiDBSessionStore implements SessionStore {
         owner: string | null;
         leafId: string | null;
     } | undefined>;
-    /** Durable history is retained; just drop any in-flight cache entry. */
+    /**
+     * Durable history is retained; just drop any in-flight cache entry.
+     *
+     * 🔴 #292 义务 4 —— **placed 会话例外:release 是真删除**(durable 史一并)。联合 reap 先按 rev 条件删
+     * 掉 agent 行、赢了才调本方法终结转录;若这里还按「归还租约」走,一条 30 天的转录就会失去属主行地
+     * 悬着(正是这条义务要关死的 strand)。判据取**持久化元组**(冷缓存/重启后照样成立,不依赖任何进程
+     * 内状态);删除本身是 ABA 安全的**条件删**(`placement_kind IS NOT NULL`)——探针与删除之间若真有
+     * 「行被删掉又以同 id 重建成普通会话」的世代翻转,条件删当场落空,不会误杀那只无辜的新会话。
+     * 删除失败**响亮上浮**(`SessionError("storage")`):吞掉失败等于让 reap 数一条「已终结」而字节还在
+     * (core File 店同批的 rmSync 失败上浮是同一条法)。
+     */
     release(sessionId: string): Promise<void>;
+    /**
+     * core B-17 的 `forget` 面 —— **丢引用,不动 durable 史**(与 {@link release} 的分工:release 是
+     * 生命周期终结口,forget 是「我用完了这只句柄」)。#292 之后这条分工是承重的:release 对 placed
+     * 会话已是真删除,于是每一处「只为验存在 / 写完收工」的收尾都必须落在 forget 上(preflight 纪律,
+     * [4743] 义务①)。本店的进程内状态只有 in-flight 去重表,故实现就是丢那一格。
+     */
+    forget(sessionId: string): void;
+    /** 真删除一只 placed 会话的两张表(条件删门在 `placement_kind IS NOT NULL`;事务内 meta 先删=提交点,
+     *  与 {@link deleteSession} 同序)。任何 I/O 失败上浮成 `SessionError("storage")`,绝不吞。 */
+    private deletePlacedSession;
     /**
      * E16 — list the caller's sessions (CC /resume picker), keyset-paginated newest-first by last activity.
      * Session IDENTITY/enumeration comes from `session_meta` (owner-filtered on the service's OWN owner column);
@@ -159,6 +205,8 @@ export declare class TiDBSessionStore implements SessionStore {
      * atomic swap) or aborts. No row is touched here — the handle is a stateless cursor over this pool.
      */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
+    /** #292:「这个 id 是 placed ⇒ 该写路径不适用」的共用拒绝(session-sync 的两条换装腿共用)。 */
+    private assertNotPlaced;
     /**
      * 2c session-sync P1d-β (staged-row inspection) — read the rows STAGED under `stagingId` (NO session_meta probe — a
      * staging id has no meta row by construction, so {@link exportEntries} would return null), oldest-first. The Phase-B