@sema-agent/server 7.10.0 → 7.11.0

package/dist/plugins/pg-pool.js

@@ -36,6 +36,8 @@ import { ensurePgOutcomeLedgerSchema as ensureOutcomeLedgerSchema } from "./outc
 import { ensureSchema as ensureImageIndexSchema } from "./image-index-sql.js";
 import { ensurePgImageBakeSchema as ensureImageBakeSchema } from "./image-bake-store-sql.js";
 import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
+import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
+import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -284,6 +286,35 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (run_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wfnotify_acked ON workflow_notify_journal (acked)`,
+    // design/177 shared-memory store —— org 盘三张表的 PG twin(MySQL 侧的逐列注释见 tidb-pool.ts;方言差
+    // 只在 TINYINT(1)→SMALLINT 与 inline KEY→独立 CREATE INDEX)。🔴 与 `agent_memory_engine_*` 零关系。
+    // 每个字符串列都带 COLLATE "C":core 的 cursor 词表是「UTF-16 code-unit 序」,而它的翻页只在
+    // `nextCursor > windowCursor`(JS 比较)成立时才继续 —— 数据库若按 locale 排序,一次列举会静默截断。
+    `CREATE TABLE IF NOT EXISTS shared_memory_scope (
+     scope_key     VARCHAR(190) COLLATE "C" NOT NULL,
+     state         VARCHAR(16) COLLATE "C"  NOT NULL,
+     message       VARCHAR(512) COLLATE "C",
+     updated_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (scope_key)
+   )`,
+    `CREATE TABLE IF NOT EXISTS shared_memory_store (
+     store_id      VARCHAR(64) COLLATE "C"  NOT NULL,
+     scope_key     VARCHAR(190) COLLATE "C" NOT NULL,
+     description   VARCHAR(512) COLLATE "C" NOT NULL,
+     writable      SMALLINT     NOT NULL DEFAULT 0,
+     updated_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (store_id)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_shared_memory_store_scope ON shared_memory_store (scope_key, store_id)`,
+    `CREATE TABLE IF NOT EXISTS shared_memory_entry (
+     store_id       VARCHAR(64) COLLATE "C"  NOT NULL,
+     path           VARCHAR(512) COLLATE "C" NOT NULL,
+     content        TEXT COLLATE "C"         NOT NULL,
+     updated_at_iso VARCHAR(64) COLLATE "C",
+     size_bytes     INTEGER      NOT NULL,
+     updated_at_ms  BIGINT       NOT NULL,
+     PRIMARY KEY (store_id, path)
+   )`,
 ];
 /** Build the pg PoolConfig from PG config (pure → unit-testable apart from the live connection) — the PG twin of
  *  tidbPoolOptions. `dbQueryTimeoutMs` (DB_QUERY_TIMEOUT_MS, S9 deeper fix) arms a POOL-WIDE per-query ceiling on
@@ -354,6 +385,12 @@ export async function ensurePgSchema(pool) {
         // `PgQueryFn`(而非兄弟们收的 client 形),故在这里绑一层 —— DDL 仍然跑在**同一条** client 上,
         // advisory lock 的 session 语义不受影响(见本函数头注:路由到别的池连接会静默作废那把锁)。
         await ensurePgApprovalAskSchema((text, params) => client.query(text, params));
+        // design/183 form b 的 SQL 收编日志(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。
+        // 同 approval-ask:收裸 query 形,故在这里绑一层——DDL 仍跑在**同一条** client 上,advisory lock 不失效。
+        await ensurePgAdoptionLogSchema((text, params) => client.query(text, params));
+        // #154 车二:持久化权限规则店三张表(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。
+        // 同上一行的绑法 —— DDL 跑在**同一条** client 上,advisory lock 的 session 语义不受影响。
+        await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
     }
     finally {
         if (locked) {

package/dist/plugins/session-policy-store-sql.d.ts

@@ -2,6 +2,12 @@ import { type SessionPolicyStore, type SessionPermissionRules, type StoredSessio
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+/** `session_policy.policy_key` 的**唯一铸造点**(core 复合键的 sha256)。
+ *
+ *  🔴 导出而不是让收编腿再抄一份(clay 宪法「schema 单一属主禁复制」):design/183 form b 的身份重绑要
+ *  逐行重算这把键(身份在 hash 的**原像**里,等值 UPDATE 够不着)。两处各写一遍 sha256 表达式的下场是
+ *  某天有人在这里改了 key 公式而收编腿还在按旧式算 —— 迁完的行从此谁也读不到,且**静默**。 */
+export declare const policyKeyFor: (sessionId: string, principal: string | undefined) => string;
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;

package/dist/plugins/session-policy-store-sql.js

@@ -43,7 +43,13 @@ import { createHash } from "node:crypto";
 import { loosenReasons, SessionPolicyError, normalizeRules, stripRev } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-const policyKey = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
+/** `session_policy.policy_key` 的**唯一铸造点**(core 复合键的 sha256)。
+ *
+ *  🔴 导出而不是让收编腿再抄一份(clay 宪法「schema 单一属主禁复制」):design/183 form b 的身份重绑要
+ *  逐行重算这把键(身份在 hash 的**原像**里,等值 UPDATE 够不着)。两处各写一遍 sha256 表达式的下场是
+ *  某天有人在这里改了 key 公式而收编腿还在按旧式算 —— 迁完的行从此谁也读不到,且**静默**。 */
+export const policyKeyFor = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
+const policyKey = policyKeyFor;
 const parseRules = (v) => (typeof v === "string" ? JSON.parse(v) : v); // R7 终形:拒绝式下库内恒干净,直读
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export class SqlSessionPolicyStore {

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -0,0 +1,223 @@
+/**
+ * design/177 — the SQL `SharedMemoryStoreProvider`: the deployment's ORG-scoped shared memory libraries
+ * (`memory_list` / `memory_read`), served out of the durable store instead of a BYOM host callback.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * WHAT THIS IS (and, just as load-bearing, what it is NOT)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * core's seam is a document-only READ face reached exclusively through two tools. There is no model
+ * write channel at all — write governance is the environment's, and the tool face's entire
+ * participation in it is relaying each store's `writable` bit verbatim. This module keeps that shape:
+ * {@link SqlSharedMemoryStore.snapshot} is the only method core ever calls; the `put*`/`delete*` half
+ * is the DEPLOYMENT's admin plane (migrations, an import job, an operator face) and is deliberately
+ * NOT reachable from any model-facing surface in this repo.
+ *
+ * 🔴 ORG PLANE ≠ THE LOCAL MEMORY CHAIN (设计 182 §13). `agent_memory_engine_*` (the design/138
+ * MemoryEngine) and these three tables share NOTHING: no join, no view, no shared row, no shared
+ * scope registry. The local chain is an entry-transactional index injection with a write path; this
+ * one is a read-only document library. Bridging them in EITHER direction would let harvested private
+ * notes leak into a team library (or a team library into a model-writable disk), which is exactly the
+ * boundary core's seam doc draws. If a future feature needs both, it composes them ABOVE this layer.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * AUTHORIZATION (v2/F4) — server-side, injected, never inferred here
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * `SharedMemoryRequestContext` carries the caller's `principal`. Who belongs to `org:acme` is NOT this
+ * module's question: it takes a {@link SharedMemoryScopeAuthorizer} and serves exactly the scopes that
+ * verdict names. The production binding folds the SAME `OrgMemoryDirectory` instance the memory-policy
+ * face and core's admission seam already read (`src/shared-memory-scope-authorizer.ts`), so a process
+ * has ONE answer to "who belongs to org:acme".
+ *
+ * The verdict is a discriminated union on purpose (same 裁定 as org-memory-admission's N3/C5): a
+ * directory that CANNOT ANSWER must never collapse into "you belong to nothing". The first renders as
+ * `unavailable` ("reads are refused until it is restored" — try again); the second renders as a
+ * settled "no memory stores are connected to this session", which teaches the model to give up. Those
+ * are opposite instructions and a fail-open collapse between them is a real defect, not a nuance.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * ORDERING / PAGINATION — why the collations are part of the contract
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * core's cursor vocabulary is "an EXCLUSIVE lower bound over document paths in plain UTF-16 code-unit
+ * order", and its paging loop only advances while `nextCursor > windowCursor` **in JavaScript**. So the
+ * SQL ordering must agree with JS string comparison or a listing would silently stop early.
+ *   · MySQL: the tables are `COLLATE utf8mb4_bin` ⇒ comparison is by code point.
+ *   · PG: every string column is `COLLATE "C"` ⇒ comparison is by UTF-8 byte, which for valid UTF-8 is
+ *     also code-point order.
+ * Code-point order equals UTF-16 code-unit order for every BMP character, and differs ONLY for
+ * supplementary-plane characters (U+10000+, whose surrogates sort before U+E000..U+FFFF in UTF-16).
+ * Rather than leave that as an invisible "listing silently truncates" hazard, {@link assertDocumentPath}
+ * REFUSES a non-BMP path at write time — the divergence is made impossible by construction, loudly, at
+ * the one place a human is watching. (Store ids and org scopes are already ASCII-only by their own
+ * shape rules, so this is the only column that needed the ruling.)
+ *
+ * KEYSET, never OFFSET: `WHERE store_id = ? AND path > ?` walks the PRIMARY KEY. An OFFSET pager over a
+ * live library both re-scans the prefix on every page and skips rows when a document is inserted mid-walk.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 事务与锁 —— 为什么用 `begin()` 而不是 `beginPessimistic()`
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 三个写方法(putStore / putDocument / deleteStore)都是「先读注册行、再按结果写」的形状,并且都用
+ * `SELECT … FOR UPDATE` 拿同一把行锁,于是彼此串行。事务动词取**普通** `begin()`:
+ *  · `BEGIN PESSIMISTIC` 是 TiDB 专有语法,在 MySQL / MariaDB 上是**语法错误**——而本仓 `kind: "mysql"`
+ *    按定义覆盖任何 MySQL 协议服务端(本机验收台就是真 MySQL 9.7)。用它等于让这个店在多数目标上直接
+ *    不可用,那比它要防的那道窄窗口严重得多;
+ *  · MySQL InnoDB 的加锁读(`FOR UPDATE`)在 REPEATABLE READ 下**恒是 current read**,读到的是最新已提交
+ *    版本,并且对不存在的键取 gap/next-key 锁 ⇒ 并发登记天然串行。TiDB 自 v5 起默认就是悲观事务,同理;
+ *  · 唯一残留的窄窗口是「TiDB 集群被显式配成乐观模式」。那一格由**第二道防线**兜底:`store_id` 的主键
+ *    唯一性是真正的裁决者,撞键被 {@link isDupKey} 翻成一句响亮的拒绝(见 putStore)。也就是说即便快照
+ *    读陈旧,结果也只会是「一方被响亮拒绝」,绝不会是一次静默的换属主。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SharedMemoryRequestContext, type SharedMemorySnapshot, type SharedMemoryStoreProvider } from "@sema-agent/core";
+import { type SqlDriver } from "./sql-driver.js";
+/** Per-org plane state (`connecting` / `unavailable` / `connected`). One row per org scope. */
+export declare const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
+/** The model-facing store registry: one row per browsable library. */
+export declare const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
+/** The documents. One row per (store, path). */
+export declare const SHARED_MEMORY_ENTRY_TABLE = "shared_memory_entry";
+/**
+ * The plane word set — CLOSED, and consumed through an exhaustive `switch` ({@link foldPlaneState}) so
+ * adding a word is a COMPILE error at every fold site rather than a silent default arm.
+ */
+export type SharedMemoryPlaneState = "connecting" | "unavailable" | "connected";
+/** The read-authorization verdict for ONE caller. See the header's "AUTHORIZATION" section for why the
+ *  `unavailable` arm may never collapse into an empty `granted`. */
+export type SharedMemoryScopeGrant = {
+    kind: "granted";
+    scopes: readonly string[];
+} | {
+    kind: "unavailable";
+    reason: string;
+};
+/** Injected org-membership fold. `principal` is `undefined` on a single-user deployment. */
+export interface SharedMemoryScopeAuthorizer {
+    resolve(principal: string | undefined): Promise<SharedMemoryScopeGrant>;
+}
+/** One store registry row, as the admin plane writes it. */
+export interface SharedMemoryStoreRecord {
+    /** The model-facing handle. GLOBALLY unique in the deployment — see {@link assertStoreId}. */
+    storeId: string;
+    /** The org scope that owns it (`org:acme`). */
+    scopeKey: string;
+    description: string;
+    /** Relayed verbatim to the model; core acts on it in no way whatsoever. */
+    writable: boolean;
+}
+/** One document, as the admin plane writes it. */
+export interface SharedMemoryDocumentRecord {
+    storeId: string;
+    /** 🔴 属主围栏(codex 复审轮3 F1):写方必须说出**它以为的**属主 org。store id 在删除后可复用,只按
+     *  id 寻址的话,一条迟到的重试会把上一任租户的内容注进新租户的库里。见 {@link SqlSharedMemoryStore.putDocument}。 */
+    scopeKey: string;
+    path: string;
+    content: string;
+    /** ISO 8601, round-tripped VERBATIM (core renders only a matching `YYYY-MM-DD` prefix). */
+    updatedAtIso?: string;
+}
+/** Tuning knobs. Both have deployment-safe defaults; neither is model-facing. */
+export interface SqlSharedMemoryStoreOptions {
+    /** Clock injection (mtime column). Default `Date.now`. */
+    now?: () => number;
+    /** Hard ceiling on ONE `list` window, whatever the caller asks for. core asks for 51; a bigger
+     *  request is an admin/HTTP caller. Default 500 — the container is bounded by declaration, not by
+     *  hope (core puts no cap on the provider's window, so the provider must state its own). */
+    maxListLimit?: number;
+}
+export declare function assertStoreId(storeId: string): void;
+export declare function assertScopeKey(scopeKey: string): void;
+/**
+ * WRITE-side document-path admission. Deliberately at least as strict as core's READ-side listing gate
+ * (`isListablePath`): a row core would silently drop is refused here where an operator can see it. The
+ * ONE rule that is stricter on purpose is the non-BMP refusal — see the header's ORDERING section.
+ */
+export declare function assertDocumentPath(path: string): void;
+/**
+ * The dual-dialect implementation. Every statement is written out in BOTH texts at its call site
+ * (design/158 A12 判据:方言差异必须显式) — the `q(tidbSql, pgSql)` helper never builds one text.
+ */
+export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
+    private readonly db;
+    private readonly authorizer;
+    private readonly now;
+    private readonly maxListLimit;
+    constructor(db: SqlDriver, authorizer: SharedMemoryScopeAuthorizer, opts?: SqlSharedMemoryStoreOptions);
+    private q;
+    /**
+     * ONE registry-binding snapshot per tool call, as core's seam requires: the state, the store identity
+     * set and each reader binding all come from this one call, so the set cannot change between "list the
+     * stores" and "resolve one". Document state stays live — which is why a store can still vanish between
+     * binding and read, the case {@link storeGone} names.
+     */
+    snapshot(ctx: SharedMemoryRequestContext, opts: {
+        signal?: AbortSignal;
+    }): Promise<SharedMemorySnapshot>;
+    /**
+     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。方言差异显式:
+     *  · MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 一个事务内的两条 SELECT 天然同快照;
+     *  · PG 默认 READ COMMITTED,**每条语句各自取快照** ⇒ 必须显式抬到 REPEATABLE READ,否则这个事务
+     *    对本条竞态毫无作用(那正是"包了事务就以为一致"最容易踩空的地方)。
+     */
+    private readBinding;
+    private readerFor;
+    /** One keyset window. Always the PAGED shape — a large library must never be materialized per call. */
+    private listDocuments;
+    /** `null` = the document does not exist. Absence is a VALUE here; only a VANISHED STORE is an error. */
+    private readDocument;
+    private storeExists;
+    /** Declare an org's plane state. Absent row ⇒ `connected` (a never-provisioned org simply has no stores). */
+    putScopeState(scopeKey: string, state: SharedMemoryPlaneState, message?: string): Promise<void>;
+    /**
+     * Register (or re-describe) one browsable store.
+     *
+     * 🔴 codex 复审轮1 F1(真缺陷,已红先复现):**属主 org 不可变**。原式是一条 upsert,`scope_key` 跟着
+     * 被改写 —— 而文档行只按 `store_id` 编键、原地不动。于是一次撞 id 的导入(管理面手滑、重试、坏配置,
+     * 零竞态)就把 A 的整座库连内容一起交给了 B,同时 A 失去它。所以这里改成:已存在的 id 只允许它自己的
+     * org 更新描述/writable 位,换 org 一律响亮拒。真要迁库,那是一次需要显式审计的搬迁(先删再建,内容
+     * 由搬迁方决定重导还是丢弃),不能是一条 upsert 的副作用。
+     *
+     * 事务 + 行锁:属主判定与写入之间不留窗口(同一把锁 {@link deleteStore} 也拿)。并发到达的两个新建
+     * 会有一个撞 PK —— 那条也翻成同一句拒绝,不让驱动错误对象漏给调用方。
+     */
+    putStore(record: SharedMemoryStoreRecord): Promise<void>;
+    /**
+     * Write one document. Refuses when the store is not registered — an orphan document is unreachable
+     * through the read face, so accepting it would be a silent no-op the writer never learns about, AND a
+     * live landmine: whoever re-registers that id later inherits it.
+     *
+     * 🔴 codex 复审轮1 F2/F3 两修:
+     *  · 帽在**入库**成立 —— 超 `SHARED_MEMORY_READ_CAP_BYTES` 的文档 core 横竖恒拒(从不截断),存下来
+     *    只是一行永远读不出来的死数据,却让每次读都要物化它。写面拒 = 那个帽在结构上为真。库里真有超大
+     *    文档的话,导入方分块——这是它自己就得做的事,因为模型面本来也读不到整份。
+     *  · 存在性检查与写入**同事务同行锁**(与 {@link deleteStore} 争同一把):否则一次并发删除可以从检查
+     *    与插入之间穿过去,留下一行孤儿文档 —— 被删的内容在 id 复用时复活。
+     */
+    putDocument(record: SharedMemoryDocumentRecord): Promise<void>;
+    /** Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
+     *  successor tenant's library). Returns whether a row was actually there. */
+    deleteDocument(storeId: string, scopeKey: string, path: string): Promise<boolean>;
+    /** 属主围栏的共用断言(轮3 F1)。**不**覆盖同一个 org 内的"删了又建"代际重用——那不是跨租户面,
+     *  真要挡住需要一枚不可变的 generation token;这里如实说明边界,不假装它被覆盖了。 */
+    private assertOwnedBy;
+    /**
+     * De-register a store AND its documents, ATOMICALLY.
+     *
+     * 🔴 codex 复审轮1 F3(真缺陷):原式是两条独立语句。崩在中间会留下「登记着但被悄悄清空」的库,而
+     * 并发的 {@link putDocument} 能从检查与插入之间穿过去留下孤儿行 —— 被删的内容会在这个 id 被重新登记时
+     * 复活。现在两条删除同事务,并且**先拿注册行的行锁**:写面争的是同一把锁,两者因此串行。
+     *
+     * 🔴 轮3 F1 同族:必须带 `scopeKey` 围栏。id 删后可复用,而一条**迟到的** deleteStore 若只按 id 寻址,
+     * 会把继任租户刚建好的库连内容一起抹掉 —— 一次歧义的重试变成一次跨租户的破坏性操作。
+     */
+    deleteStore(storeId: string, scopeKey: string): Promise<void>;
+}
+/** MySQL-protocol (MySQL / TiDB) binding. */
+export declare class TiDBSharedMemoryStore extends SqlSharedMemoryStore {
+    constructor(pool: MySqlPool, authorizer: SharedMemoryScopeAuthorizer, opts?: SqlSharedMemoryStoreOptions);
+}
+/** PostgreSQL binding. */
+export declare class PgSharedMemoryStore extends SqlSharedMemoryStore {
+    constructor(pool: PgPool, authorizer: SharedMemoryScopeAuthorizer, opts?: SqlSharedMemoryStoreOptions);
+}
+//# sourceMappingURL=shared-memory-store-sql.d.ts.map