@sema-agent/server 7.132.0 → 7.133.0

package/dist/plugins/org-delivery-quota-store.d.ts

@@ -0,0 +1,123 @@
+import type { Pool as MysqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver } from "./sql-driver.js";
+/** 发件人行表(单数形;`test/schema-naming-invariants.test.ts` 的闭集词表钉着)。 */
+export declare const ORG_DELIVERY_SENDER_QUOTA_TABLE = "org_delivery_sender_quota";
+/** 收件人行表。 */
+export declare const ORG_DELIVERY_RECIPIENT_QUOTA_TABLE = "org_delivery_recipient_quota";
+/** 对偶行表。 */
+export declare const ORG_DELIVERY_PAIR_QUOTA_TABLE = "org_delivery_pair_quota";
+/** 门用的那份额度。门持有它(唯一的数字源在 `org-delivery-gate.ts`),店只按它数。 */
+export interface OrgDeliveryQuotaPolicy {
+    /** 固定窗宽(毫秒)。 */
+    readonly windowMs: number;
+    /** 一个发件人在一个窗里能做的投递尝试数上界(成没成都算)。 */
+    readonly attemptsPerSender: number;
+    /** 同一个发件人在一个窗里能投给同一个收件人的封数上界。 */
+    readonly perPair: number;
+    /** 一个收件人在一个窗里能收的封数上界(全部发件人合计)。 */
+    readonly perRecipient: number;
+}
+export interface OrgDeliveryQuotaStore {
+    /**
+     * 原子地把这位发件人的一次投递**尝试**算进店钟当前窗:未满 ⇒ +1、答 `true`;已满 ⇒ 什么都不记、答 `false`。
+     * 店读不出 / 写不进 ⇒ **抛**(调用方按失败处置,绝不当成「放行」)。
+     */
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    /**
+     * 原子地把一封 (fromScope → toScope) 的信算进**店钟当前窗**的两只计数器:两界都未满 ⇒ 两只各 +1、答 `true`;
+     * 任一界已满 ⇒ 什么都不记、答 `false`。店读不出 / 写不进 ⇒ **抛**。
+     */
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+}
+/** 窗起点(一处算法,三条腿共用)。 */
+export declare function quotaWindowStart(nowMs: number, windowMs: number): number;
+/** 店里记着的那个窗(`heldStart`)的计数此刻还算不算数 —— 头注那条律的**唯一**写法:此刻的窗,或此刻的下一个窗。 */
+export declare function heldWindowCounts(heldStart: number, at: number, windowMs: number): boolean;
+/** 一位发件人的当前窗(`windowMs` = 开窗那一次的窗宽:窗何时结束是条目自己的事实,File 腿据它丢已过窗的条目)。 */
+interface SenderWindow {
+    windowStart: number;
+    windowMs: number;
+    attempts: number;
+}
+/** 一位收件人的当前窗。 */
+interface RecipientWindow {
+    windowStart: number;
+    windowMs: number;
+    total: number;
+    /** fromScope → 本窗已投封数。 */
+    pairs: Map<string, number>;
+}
+/** 两张窗表(Memory 腿的全部状态;File 腿整份落盘的就是它)。 */
+interface QuotaWindows {
+    senders: Map<string, SenderWindow>;
+    recipients: Map<string, RecipientWindow>;
+}
+export declare class MemoryOrgDeliveryQuotaStore implements OrgDeliveryQuotaStore {
+    protected readonly nowMs: () => number;
+    protected state: QuotaWindows;
+    /** @param nowMs 店钟(单进程腿:店 = 这个进程,缺省本进程墙钟)。 */
+    constructor(nowMs?: () => number);
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    /**
+     * 落新的整份状态,只留窗还没结束的条目(按条目自己的窗宽判;已结束的发件人 / 收件人整个丢掉 —— 有界:量 = 本窗活跃的主体数)。
+     * 丢掉的条目按头注那条律本来就不再算数(过去的窗),所以剪枝不改任何判决;剪枝写在**这里**而不是 File 腿里,Memory 与 File
+     * 因此对同一串记账逐笔同判(墙钟回拨的那一形也同判)。File 腿覆写 {@link persist}:先落盘、再换内存(反过来的话,一次写盘失败
+     * 会留下「内存记了、盘上没有」)。
+     */
+    protected commit(next: QuotaWindows): void;
+    /** Memory 腿无盘可落。 */
+    protected persist(_next: QuotaWindows): void;
+}
+/**
+ * local 车道的配额店:Memory 腿的同一份算法 + 每次记账后**整份原子改写**一个 JSON 快照(`atomicWriteFile`:
+ * 同盘临时文件 + rename,崩溃只会留下旧的或新的整份,不会留半份)。
+ *
+ * 为什么是整份快照而不是追加日志:快照只装「当前窗」(写入时顺手丢掉已过窗的发件人 / 收件人),量 = 本窗活跃的主体数,
+ * 每次记账改写一次的代价与它同阶;追加日志则要再带一套压实与断尾规则。记账频次本来就被本店自己界住。
+ *
+ * 🔴 读不出的快照 ⇒ **拒用**(fail-closed,响亮):每一次记账都抛,出路在拒句里(移开文件 = 本窗计数清零)。
+ * 跳过坏文件当成「没记过」= 一次位腐就把整个配额窗放开,那是放行方向的静默降级。
+ */
+export declare class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
+    private readonly path;
+    private readonly tmpDir;
+    /** 快照读不出时的拒句(在场 ⇒ 店拒用)。 */
+    private readonly unusable;
+    constructor(root: string, opts?: {
+        nowMs?: () => number;
+        warn?: (event: string, fields: Record<string, unknown>) => void;
+    });
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    protected persist(next: QuotaWindows): void;
+}
+export declare class SqlOrgDeliveryQuotaStore implements OrgDeliveryQuotaStore {
+    private readonly db;
+    constructor(db: SqlDriver);
+    private q;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    /**
+     * 一个记账事务:库钟先读(池上一条值语句,不在事务里留普通 SELECT),判过 ⇒ 提交,判拒 ⇒ 回滚(零残留)。
+     * 🔴 **引擎判了死锁 ⇒ 整事务重来**(有界,`isDeadlockError` 是全仓唯一的可重试锁故障判据):被挑中的一方已整事务回滚、锁全放,
+     * 重来时读-判-写全部重做,语义等价。真 InnoDB(REPEATABLE READ)上这条路是真的:窗前进时按收件人前缀删旧对偶行要取范围 / 间隙锁,
+     * 两位相邻收件人同时翻窗、各自往两人之间的间隙里插新对偶行 ⇒ 互等(TiDB 无间隙锁、PG 读已提交不取间隙锁)。谁当牺牲者是引擎的任意选择,
+     * 抛给调用方等于把一次内部仲裁当成投递失败。锁等待超时**不**重来(延迟信号,照抛)。
+     */
+    private inTx;
+    private inTxOnce;
+    private admitIn;
+    private takeIn;
+}
+/** MySQL 协议腿的构造绑定。 */
+export declare class TiDBOrgDeliveryQuotaStore extends SqlOrgDeliveryQuotaStore {
+    constructor(pool: MysqlPool);
+}
+/** PostgreSQL 腿的构造绑定。 */
+export declare class PgOrgDeliveryQuotaStore extends SqlOrgDeliveryQuotaStore {
+    constructor(pool: PgPool);
+}
+export {};
+//# sourceMappingURL=org-delivery-quota-store.d.ts.map

package/dist/plugins/org-delivery-quota-store.js

@@ -0,0 +1,228 @@
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { atomicWriteFile, ensureDir } from "@sema-agent/core";
+import { mysqlDriver, pgDriver, sqlDbNowMs } from "./sql-driver.js";
+import { isDeadlockError } from "./sql-errors.js";
+import { alignedWindow } from "../observability/cost-quota.js";
+export const ORG_DELIVERY_SENDER_QUOTA_TABLE = "org_delivery_sender_quota";
+export const ORG_DELIVERY_RECIPIENT_QUOTA_TABLE = "org_delivery_recipient_quota";
+export const ORG_DELIVERY_PAIR_QUOTA_TABLE = "org_delivery_pair_quota";
+export function quotaWindowStart(nowMs, windowMs) {
+    return alignedWindow(nowMs, windowMs).bucket * windowMs;
+}
+export function heldWindowCounts(heldStart, at, windowMs) {
+    return heldStart === at || heldStart === at + windowMs;
+}
+export class MemoryOrgDeliveryQuotaStore {
+    nowMs;
+    state = { senders: new Map(), recipients: new Map() };
+    constructor(nowMs = Date.now) {
+        this.nowMs = nowMs;
+    }
+    async admitAttempt(fromScope, policy) {
+        const at = quotaWindowStart(this.nowMs(), policy.windowMs);
+        const held = this.state.senders.get(fromScope);
+        const current = held !== undefined && heldWindowCounts(held.windowStart, at, policy.windowMs) ? held : { windowStart: at, windowMs: policy.windowMs, attempts: 0 };
+        if (current.attempts >= policy.attemptsPerSender)
+            return false;
+        const senders = new Map(this.state.senders).set(fromScope, { ...current, attempts: current.attempts + 1 });
+        this.commit({ senders, recipients: this.state.recipients });
+        return true;
+    }
+    async take(fromScope, toScope, policy) {
+        const at = quotaWindowStart(this.nowMs(), policy.windowMs);
+        const held = this.state.recipients.get(toScope);
+        const current = held !== undefined && heldWindowCounts(held.windowStart, at, policy.windowMs) ? held : { windowStart: at, windowMs: policy.windowMs, total: 0, pairs: new Map() };
+        const pair = current.pairs.get(fromScope) ?? 0;
+        if (current.total >= policy.perRecipient || pair >= policy.perPair)
+            return false;
+        const next = { ...current, total: current.total + 1, pairs: new Map(current.pairs).set(fromScope, pair + 1) };
+        this.commit({ senders: this.state.senders, recipients: new Map(this.state.recipients).set(toScope, next) });
+        return true;
+    }
+    commit(next) {
+        const now = this.nowMs();
+        const live = (m) => new Map([...m].filter(([, w]) => w.windowStart + w.windowMs > now));
+        const pruned = { senders: live(next.senders), recipients: live(next.recipients) };
+        this.persist(pruned);
+        this.state = pruned;
+    }
+    persist(_next) { }
+}
+const isCount = (x) => typeof x === "number" && Number.isInteger(x) && x >= 0;
+const isWidth = (x) => isCount(x) && x > 0;
+const isPlain = (x) => x !== null && typeof x === "object" && !Array.isArray(x) && Object.getPrototypeOf(x) === Object.prototype;
+function readSnapshot(raw) {
+    if (!isPlain(raw) || raw.v !== 1 || !isPlain(raw.senders) || !isPlain(raw.recipients))
+        return { ok: false, problem: "expected { v: 1, senders: {…}, recipients: {…} }" };
+    const senders = new Map();
+    for (const [from, entry] of Object.entries(raw.senders)) {
+        if (!isPlain(entry) || !isCount(entry.w) || !isWidth(entry.ms) || !isCount(entry.n))
+            return { ok: false, problem: `sender ${JSON.stringify(from)} is not { w, ms, n }` };
+        senders.set(from, { windowStart: entry.w, windowMs: entry.ms, attempts: entry.n });
+    }
+    const recipients = new Map();
+    for (const [to, entry] of Object.entries(raw.recipients)) {
+        if (!isPlain(entry) || !isCount(entry.w) || !isWidth(entry.ms) || !isCount(entry.n) || !isPlain(entry.pairs))
+            return { ok: false, problem: `recipient ${JSON.stringify(to)} is not { w, ms, n, pairs }` };
+        const pairs = new Map();
+        for (const [from, n] of Object.entries(entry.pairs)) {
+            if (!isCount(n))
+                return { ok: false, problem: `pair ${JSON.stringify([to, from])} is not a count` };
+            pairs.set(from, n);
+        }
+        recipients.set(to, { windowStart: entry.w, windowMs: entry.ms, total: entry.n, pairs });
+    }
+    return { ok: true, state: { senders, recipients } };
+}
+export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
+    path;
+    tmpDir;
+    unusable;
+    constructor(root, opts) {
+        super(opts?.nowMs);
+        const dir = join(root, "org-delivery-quota");
+        ensureDir(dir);
+        this.tmpDir = join(dir, ".tmp");
+        ensureDir(this.tmpDir);
+        this.path = join(dir, "windows.json");
+        if (!existsSync(this.path))
+            return;
+        let parsed;
+        try {
+            parsed = readSnapshot(JSON.parse(readFileSync(this.path, "utf8")));
+        }
+        catch (err) {
+            parsed = { ok: false, problem: err instanceof Error ? err.message : String(err) };
+        }
+        if (!parsed.ok) {
+            this.unusable = `the cross-principal delivery quota file ${this.path} cannot be read (${parsed.problem}) — every delivery is refused until an operator moves it away (moving it resets the current window's counts)`;
+            (opts?.warn ?? ((event, fields) => console.warn(event, fields)))("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
+            return;
+        }
+        this.state = parsed.state;
+    }
+    async admitAttempt(fromScope, policy) {
+        if (this.unusable !== undefined)
+            throw new Error(this.unusable);
+        return super.admitAttempt(fromScope, policy);
+    }
+    async take(fromScope, toScope, policy) {
+        if (this.unusable !== undefined)
+            throw new Error(this.unusable);
+        return super.take(fromScope, toScope, policy);
+    }
+    persist(next) {
+        const { senders, recipients } = next;
+        const snapshot = {
+            v: 1,
+            senders: Object.fromEntries([...senders].map(([from, w]) => [from, { w: w.windowStart, ms: w.windowMs, n: w.attempts }])),
+            recipients: Object.fromEntries([...recipients].map(([to, w]) => [to, { w: w.windowStart, ms: w.windowMs, n: w.total, pairs: Object.fromEntries(w.pairs) }])),
+        };
+        atomicWriteFile(this.tmpDir, this.path, `${JSON.stringify(snapshot)}\n`);
+    }
+}
+const DEADLOCK_RETRY_LIMIT = 3;
+export class SqlOrgDeliveryQuotaStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    async admitAttempt(fromScope, policy) {
+        return this.inTx(ORG_DELIVERY_SENDER_QUOTA_TABLE, policy, (conn, at) => this.admitIn(conn, fromScope, at, policy));
+    }
+    async take(fromScope, toScope, policy) {
+        return this.inTx(ORG_DELIVERY_RECIPIENT_QUOTA_TABLE, policy, (conn, at) => this.takeIn(conn, fromScope, toScope, at, policy));
+    }
+    async inTx(table, policy, body) {
+        for (let tries = 0;; tries++) {
+            try {
+                return await this.inTxOnce(table, policy, body);
+            }
+            catch (err) {
+                if (tries < DEADLOCK_RETRY_LIMIT && isDeadlockError(this.db.dialect, err))
+                    continue;
+                throw err;
+            }
+        }
+    }
+    async inTxOnce(table, policy, body) {
+        const at = quotaWindowStart(await sqlDbNowMs(this.db, table), policy.windowMs);
+        const conn = await this.db.connect();
+        try {
+            await conn.begin();
+            const granted = await body(conn, at);
+            if (granted)
+                await conn.commit();
+            else
+                await conn.rollback();
+            return granted;
+        }
+        catch (err) {
+            await conn.rollback().catch((rollbackErr) => {
+                throw new AggregateError([err, rollbackErr], `${table}: the quota transaction failed and its rollback failed too`);
+            });
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async admitIn(conn, fromScope, at, policy) {
+        const S = ORG_DELIVERY_SENDER_QUOTA_TABLE;
+        await conn.query(this.q(`INSERT INTO ${S} (from_scope, window_start_ms, attempts) VALUES (?, ?, 0) ON DUPLICATE KEY UPDATE from_scope = from_scope`, `INSERT INTO ${S} (from_scope, window_start_ms, attempts) VALUES ($1, $2, 0) ON CONFLICT (from_scope) DO NOTHING`), [fromScope, at]);
+        const { rows } = await conn.query(this.q(`SELECT window_start_ms, attempts FROM ${S} WHERE from_scope = ? FOR UPDATE`, `SELECT window_start_ms, attempts FROM ${S} WHERE from_scope = $1 FOR UPDATE`), [fromScope]);
+        const held = rows[0];
+        if (held === undefined)
+            throw new Error(`${S}: the sender row for ${JSON.stringify(fromScope)} vanished inside its own transaction`);
+        const heldStart = Number(held.window_start_ms);
+        const counts = heldWindowCounts(heldStart, at, policy.windowMs);
+        const windowStart = counts ? heldStart : at;
+        const attempts = counts ? Number(held.attempts) : 0;
+        if (attempts >= policy.attemptsPerSender)
+            return false;
+        await conn.query(this.q(`UPDATE ${S} SET window_start_ms = ?, attempts = ? WHERE from_scope = ?`, `UPDATE ${S} SET window_start_ms = $1, attempts = $2 WHERE from_scope = $3`), [windowStart, attempts + 1, fromScope]);
+        return true;
+    }
+    async takeIn(conn, fromScope, toScope, at, policy) {
+        const R = ORG_DELIVERY_RECIPIENT_QUOTA_TABLE;
+        const P = ORG_DELIVERY_PAIR_QUOTA_TABLE;
+        await conn.query(this.q(`INSERT INTO ${R} (to_scope, window_start_ms, delivered) VALUES (?, ?, 0) ON DUPLICATE KEY UPDATE to_scope = to_scope`, `INSERT INTO ${R} (to_scope, window_start_ms, delivered) VALUES ($1, $2, 0) ON CONFLICT (to_scope) DO NOTHING`), [toScope, at]);
+        const { rows: rr } = await conn.query(this.q(`SELECT window_start_ms, delivered FROM ${R} WHERE to_scope = ? FOR UPDATE`, `SELECT window_start_ms, delivered FROM ${R} WHERE to_scope = $1 FOR UPDATE`), [toScope]);
+        const held = rr[0];
+        if (held === undefined)
+            throw new Error(`${R}: the recipient row for ${JSON.stringify(toScope)} vanished inside its own transaction`);
+        const heldStart = Number(held.window_start_ms);
+        const rolls = !heldWindowCounts(heldStart, at, policy.windowMs);
+        const windowStart = rolls ? at : heldStart;
+        const total = rolls ? 0 : Number(held.delivered);
+        if (rolls) {
+            await conn.query(this.q(`DELETE FROM ${P} WHERE to_scope = ? AND window_start_ms <> ?`, `DELETE FROM ${P} WHERE to_scope = $1 AND window_start_ms <> $2`), [toScope, windowStart]);
+        }
+        await conn.query(this.q(`INSERT INTO ${P} (to_scope, from_scope, window_start_ms, delivered) VALUES (?, ?, ?, 0) ON DUPLICATE KEY UPDATE to_scope = to_scope`, `INSERT INTO ${P} (to_scope, from_scope, window_start_ms, delivered) VALUES ($1, $2, $3, 0) ON CONFLICT (to_scope, from_scope) DO NOTHING`), [toScope, fromScope, windowStart]);
+        const { rows: pr } = await conn.query(this.q(`SELECT window_start_ms, delivered FROM ${P} WHERE to_scope = ? AND from_scope = ? FOR UPDATE`, `SELECT window_start_ms, delivered FROM ${P} WHERE to_scope = $1 AND from_scope = $2 FOR UPDATE`), [toScope, fromScope]);
+        const pairRow = pr[0];
+        if (pairRow === undefined)
+            throw new Error(`${P}: the pair row for ${JSON.stringify([toScope, fromScope])} vanished inside its own transaction`);
+        const pair = Number(pairRow.window_start_ms) === windowStart ? Number(pairRow.delivered) : 0;
+        if (total >= policy.perRecipient || pair >= policy.perPair)
+            return false;
+        await conn.query(this.q(`UPDATE ${R} SET window_start_ms = ?, delivered = ? WHERE to_scope = ?`, `UPDATE ${R} SET window_start_ms = $1, delivered = $2 WHERE to_scope = $3`), [windowStart, total + 1, toScope]);
+        await conn.query(this.q(`UPDATE ${P} SET window_start_ms = ?, delivered = ? WHERE to_scope = ? AND from_scope = ?`, `UPDATE ${P} SET window_start_ms = $1, delivered = $2 WHERE to_scope = $3 AND from_scope = $4`), [windowStart, pair + 1, toScope, fromScope]);
+        return true;
+    }
+}
+export class TiDBOrgDeliveryQuotaStore extends SqlOrgDeliveryQuotaStore {
+    constructor(pool) {
+        super(mysqlDriver(pool));
+    }
+}
+export class PgOrgDeliveryQuotaStore extends SqlOrgDeliveryQuotaStore {
+    constructor(pool) {
+        super(pgDriver(pool));
+    }
+}
+//# sourceMappingURL=org-delivery-quota-store.js.map

package/dist/plugins/pg-pool.js

@@ -19,6 +19,7 @@ import { ensurePgRetentionSchema } from "./retention-store-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
+import { PRINCIPAL_MAX_LENGTH } from "../security.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -140,6 +141,25 @@ export const PG_SCHEMA_STATEMENTS = [
      consumed_at_ms BIGINT         NOT NULL,
      expires_at_ms  BIGINT         NOT NULL,
      PRIMARY KEY (session_id, nonce)
+   )`,
+    `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
+     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     window_start_ms BIGINT       NOT NULL,
+     attempts        INT          NOT NULL,
+     PRIMARY KEY (from_scope)
+   )`,
+    `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
+     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     window_start_ms BIGINT       NOT NULL,
+     delivered       INT          NOT NULL,
+     PRIMARY KEY (to_scope)
+   )`,
+    `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
+     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     window_start_ms BIGINT       NOT NULL,
+     delivered       INT          NOT NULL,
+     PRIMARY KEY (to_scope, from_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS user_input_acceptance (
      accept_id         VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -263,17 +283,19 @@ export const PG_SCHEMA_STATEMENTS = [
    )`,
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) COLLATE "C" NOT NULL,
+     incarnation   VARCHAR(64)  COLLATE "C" NOT NULL,
      ordinal       INT          NOT NULL,
-     -- SVC-2 / CORE-9 audit BLOCKER: cross-tenant resume isolation (the WorkflowJournalStore seam takes a scope
-     -- param). NOT NULL DEFAULT '' — a row written without a scope lands in the '' bucket, which is
-     -- CROSS-SCOPE-ORPHANED but harmless: a real resume always filters \`WHERE scope = <caller>\`, so '' rows are
-     -- never handed to a tenant. Keep the DEFAULT: it is what makes a scope-less write land in that dead bucket
-     -- instead of failing or leaking into a real tenant's scope.
-     scope         VARCHAR(190) COLLATE "C" NOT NULL DEFAULT '',
      call_key      VARCHAR(255) COLLATE "C" NOT NULL,
      result        TEXT COLLATE "C"         NOT NULL,
      created_at_ms BIGINT       NOT NULL,
-     PRIMARY KEY (run_id, ordinal)
+     PRIMARY KEY (run_id, incarnation, ordinal)
+   )`,
+    `CREATE TABLE IF NOT EXISTS workflow_journal_owner (
+     run_id         VARCHAR(191) COLLATE "C" NOT NULL,
+     scope          VARCHAR(190) COLLATE "C" NOT NULL,
+     incarnation    VARCHAR(64)  COLLATE "C" NOT NULL,
+     appended_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (run_id)
    )`,
     `CREATE TABLE IF NOT EXISTS workflow_resume_claim (
      source_run_id VARCHAR(191) COLLATE "C" NOT NULL,
@@ -298,6 +320,16 @@ export const PG_SCHEMA_STATEMENTS = [
      agent_key  VARCHAR(191) COLLATE "C" NOT NULL,
      scope      VARCHAR(190) COLLATE "C" NOT NULL,
      PRIMARY KEY (session_id, run_id)
+   )`,
+    `CREATE TABLE IF NOT EXISTS workflow_park_decision (
+     token             VARCHAR(120) COLLATE "C" NOT NULL,
+     run_id            VARCHAR(191) COLLATE "C" NOT NULL,
+     host_session_id   VARCHAR(190) COLLATE "C" NOT NULL,
+     outcome           TEXT COLLATE "C"         NOT NULL,
+     fingerprint       VARCHAR(64) COLLATE "C"  NOT NULL,
+     delivered_task_id VARCHAR(191) COLLATE "C" NOT NULL,
+     accepted_at_ms    BIGINT       NOT NULL,
+     PRIMARY KEY (token)
    )`,
     `CREATE TABLE IF NOT EXISTS workflow_completion_inbox (
      seq            BIGSERIAL,

package/dist/plugins/pg-session-storage.d.ts

@@ -1,8 +1,9 @@
-import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionMetadata, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
 import { type SessionRowPatch } from "../session-row.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
+import { type OrphanOwnerLog } from "../delegated-session-owner.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type SessionFace } from "../session-incarnation.js";
@@ -65,12 +66,24 @@ export declare class PgSessionStore implements SessionStore {
     };
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
-    constructor(pool: Pool);
+    /** 委派子代孤行那一行 warn 的去处(TiDB 孪生同格)。 */
+    private readonly log;
+    constructor(pool: Pool, opts?: {
+        readonly log?: OrphanOwnerLog;
+    });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
-    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
+    /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
+    register(sessionId: string, owner: string | null): Promise<void>;
+    /** acquire 的建行(唯一一处;S-1770 委派继承律,只住在 `createPlacedSessionRow`,本店交既有读写口 —— TiDB 孪生同名方法同注)。 */
+    private createOnAcquire;
+    /** S-1770 委派继承律的认领口(TiDB 孪生 {@link TiDBSessionStore.claimOwnerless} 同义;句 = `CLAIM_OWNERLESS_PLACED_SQL`,规则在 `delegated-session-owner.ts`)。 */
+    claimOwnerless(sessionId: string, incarnation: string, owner: string): Promise<boolean>;
+    /** 若干来源行的会话面(属主 + 化身)一次读回(TiDB 孪生同义;化身经与 `sessionFaceOf` 同一只解码,空 ⇒ 响亮拒)。 */
+    private sourceFaces;
+    /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
-    register(sessionId: string, owner: string | null, placement?: SessionPlacement): Promise<void>;
+    private insertMeta;
     /** [ref] 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     /** [ref] 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,

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

@@ -9,6 +9,8 @@ import { pgSafeJsonStringify } from "./pg-safe-json.js";
 import { toIso } from "./sql-row-helpers.js";
 import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
+import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
+import { createLogger } from "../observability/logger.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
@@ -83,10 +85,10 @@ export class PgSessionStorage extends BaseSessionStorage {
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
-        return scanEpochAnchor(this.sessionId, this.floorSeq, async (beforeSeq) => {
+        return scanEpochAnchor(this.floorSeq, async (beforeSeq) => {
             const res = await this.pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq < $2 AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`, [this.sessionId, beforeSeq]);
             return res.rows;
-        });
+        }, (row) => decodeSessionEventPayload(row.payload, this.sessionId, row.seq));
     }
     static async wake(pool, sessionId) {
         const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
@@ -175,13 +177,15 @@ export class PgSessionStore {
     retention = MANAGED_RETENTION;
     placements = SQL_SESSION_PLACEMENTS;
     pending = new Map();
-    constructor(pool) {
+    log;
+    constructor(pool, opts = {}) {
         this.pool = pool;
+        this.log = opts.log ?? createLogger();
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
             const id = uuidv7();
-            await this.register(id, null, opts?.placement);
+            await this.createOnAcquire(id, opts?.placement);
             return this.load(id, false, opts);
         }
         if (opts?.requireExisting)
@@ -204,7 +208,7 @@ export class PgSessionStore {
         }
         if (requireExisting)
             throw new SessionError("not_found", `session ${sessionId} not found`);
-        await this.register(sessionId, null, opts?.placement);
+        await this.createOnAcquire(sessionId, opts?.placement);
         storage = await PgSessionStorage.wake(this.pool, sessionId);
         if (!storage) {
             throw new SessionError("storage", `session ${sessionId} vanished between register and wake (a concurrent purge won the race) — retry`);
@@ -212,7 +216,26 @@ export class PgSessionStore {
         assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
         return { session: new StoredSession(storage), sessionId };
     }
-    async register(sessionId, owner, placement) {
+    async register(sessionId, owner) {
+        await this.insertMeta(sessionId, owner, undefined);
+    }
+    async createOnAcquire(sessionId, placement) {
+        if (placement === undefined)
+            return this.insertMeta(sessionId, null, undefined);
+        await createPlacedSessionRow(sessionId, placement, {
+            readFaces: (ids) => this.sourceFaces(ids),
+            insert: (owner) => this.insertMeta(sessionId, owner, placement),
+            readOwner: () => this.ownerOf(sessionId),
+        }, this.log);
+    }
+    async claimOwnerless(sessionId, incarnation, owner) {
+        return ((await this.pool.query(CLAIM_OWNERLESS_PLACED_SQL.pg, [...claimOwnerlessParams(sessionId, incarnation, owner)])).rowCount ?? 0) > 0;
+    }
+    async sourceFaces(ids) {
+        const res = await this.pool.query(`SELECT session_id, owner, incarnation FROM session_meta WHERE session_id IN (${ids.map((_, i) => `$${i + 1}`).join(", ")})`, [...ids]);
+        return new Map(res.rows.map((r) => [String(r.session_id), sessionFaceFromRow(String(r.session_id), r.owner ?? null, r.incarnation)]));
+    }
+    async insertMeta(sessionId, owner, placement) {
         const now = new Date();
         await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
             "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +

package/dist/plugins/remote-env-adb.d.ts

@@ -1,20 +1,12 @@
 import { spawn } from "node:child_process";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
-export interface AdbEnvConfig {
+export interface AdbEnvConfig extends LaneHomeConfig {
     /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
     serial: string;
     /** Path to the adb binary. Default "adb" (must be on PATH in the runner image). */
     adbPath?: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** On-device workspace root; relative paths resolve against it. Default "/data/local/tmp". */
     mountPath?: string;
     commandTimeoutMs?: number;
@@ -86,8 +78,10 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     private destroyed;
     /** 在飞的那一次懒连接(单飞记忆)——见 {@link ensureConnected}。settle 即清,**不缓存败诺**。 */
     private connectPromise?;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):设备 shell 里执行用户的 home —— 声明胜,否则首连时 `adb shell` 实测的 `$HOME`(Android 常为 `/` 或 `/data/local/tmp` 一类,读到什么填什么,绝对即可),见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(声明胜 · 否则首连时实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道**不对证**声明:Android 没有 POSIX 登录家目录,声明是运维的断言,照单全收。 */
+    private readonly homeSeat;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 Android 设备的 shell 里(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";

package/dist/plugins/remote-env-adb.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
@@ -31,7 +32,10 @@ export class RemoteAdbExecutionEnv {
     connected = false;
     destroyed = false;
     connectPromise;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     cdPath = "unknown";
     cfg;
     spawnFn;
@@ -46,7 +50,7 @@ export class RemoteAdbExecutionEnv {
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 800 },
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: false, onAbsent: config.onHomeAbsent });
         this.spawnFn = deps?.spawn ?? spawn;
         this.injectedConnectOnce = deps?.connectOnce;
     }
@@ -117,6 +121,12 @@ export class RemoteAdbExecutionEnv {
                     error: new RemoteExecutionError("unsupported", `device ${this.cfg.serial} does not advertise the 'shell_v2' feature, so this adapter cannot establish that its command round-trip carries a real exit code with stderr kept separate — the two properties every filesystem judgment on this lane depends on to tell failure from success. Refusing to connect rather than run on an unverifiable transport: attach a device that supports adb shell protocol v2.`),
                 };
             }
+            if (this.homeSeat.asks) {
+                const home = await this.adb(this.deviceShellArgs(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.commandTimeoutMs });
+                if (!home.ok && home.error.code === "aborted")
+                    return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while reading the device's home") };
+                this.homeSeat.settle(home.ok && home.value.exitCode === 0 ? { ok: true, stdout: home.value.stdout } : { ok: false, reason: home.ok ? `exit ${home.value.exitCode}` : home.error.message });
+            }
             this.connected = true;
             return ok(this.workspaceHandle());
         }