@sema-agent/server 4.1.0 → 4.1.2

package/dist/plugins/sql-driver.d.ts

@@ -60,7 +60,12 @@
  *   $n::jsonb) · null-safe compare (<=> vs IS NOT DISTINCT FROM) AND its placeholder-arity fallout ·
  *   key-column byte semantics (VARBINARY vs COLLATE "C") · isolation/txn verbs · error classification
  *   (ER_DUP_ENTRY/errno vs SQLSTATE, sqlMessage vs err.constraint) · PG-only protocol-byte handling
- *   (pgSafeJsonStringify / pgProtocolJsonStringify / pgSanitizeText / pgHasUnstorable) · DDL.
+ *   (pgSafeJsonStringify / pgProtocolJsonStringify / pgSanitizeText / pgHasUnstorable) · DDL. Each arm's
+ *   BEHAVIOR (what pgSafeJsonStringify/pgProtocolJsonStringify actually do to the bytes) stays written out
+ *   in `pg-safe-json.ts`, untouched — `dialectJsonEncoder`/`dialectProtocolJsonEncoder` below (design/158
+ *   redesign①) only collect the identical `dialect === "tidb" ? JSON.stringify(v) : pgSafe…(v)` DISPATCH
+ *   ternary that five call sites duplicated verbatim; they are not a new abstraction over the encodings
+ *   themselves, so this does not violate the rule above.
  *
  * WHAT MAY BE PARAMETERIZED
  *   result unwrapping (rows/affected) · transaction plumbing · numeric coercion of BIGINT-as-string
@@ -99,4 +104,15 @@ export interface SqlDriver extends SqlExec {
 export declare function mysqlDriver(pool: MySqlPool): SqlDriver;
 /** PostgreSQL driver. Transaction control is issued as STATEMENTS (node-pg has no native verbs). */
 export declare function pgDriver(pool: PgPool): SqlDriver;
+/** design/158 redesign① — the "safe" JSON-column encoder DISPATCH (run-store/outcome-ledger's identical
+ *  ternary, collected): TiDB stores `JSON.stringify` verbatim; PG goes through `pgSafeJsonStringify`'s
+ *  protocol-byte defenses (a raw NUL/lone-surrogate would otherwise throw mid-write). Returns a 1-arg
+ *  encoder; call sites invoke `dialectJsonEncoder(this.db.dialect)(value)` inline — the dispatch is the
+ *  collected thing, not a cached field. */
+export declare const dialectJsonEncoder: (dialect: SqlDialect) => ((v: unknown) => string);
+/** design/158 redesign① — the "protocol" JSON-column encoder DISPATCH (approval-store/checkpoint-store's
+ *  identical ternary, collected): TiDB stores `JSON.stringify` verbatim (the `label` arg is ignored on that
+ *  arm — TiDB has no protocol-byte envelope to name); PG goes through `pgProtocolJsonStringify(v, label)`,
+ *  whose `label` names the field in its error text on an unstorable-byte reject. */
+export declare const dialectProtocolJsonEncoder: (dialect: SqlDialect) => ((v: unknown, label: string) => string);
 //# sourceMappingURL=sql-driver.d.ts.map

package/dist/plugins/sql-driver.js

@@ -1,3 +1,4 @@
+import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
 /** mysql2 hands back `[rows]` for a SELECT and `[ResultSetHeader]` for a write. */
 function mysqlResult(r) {
     if (Array.isArray(r))
@@ -60,4 +61,15 @@ export function pgDriver(pool) {
         },
     };
 }
+/** design/158 redesign① — the "safe" JSON-column encoder DISPATCH (run-store/outcome-ledger's identical
+ *  ternary, collected): TiDB stores `JSON.stringify` verbatim; PG goes through `pgSafeJsonStringify`'s
+ *  protocol-byte defenses (a raw NUL/lone-surrogate would otherwise throw mid-write). Returns a 1-arg
+ *  encoder; call sites invoke `dialectJsonEncoder(this.db.dialect)(value)` inline — the dispatch is the
+ *  collected thing, not a cached field. */
+export const dialectJsonEncoder = (dialect) => dialect === "tidb" ? JSON.stringify : pgSafeJsonStringify;
+/** design/158 redesign① — the "protocol" JSON-column encoder DISPATCH (approval-store/checkpoint-store's
+ *  identical ternary, collected): TiDB stores `JSON.stringify` verbatim (the `label` arg is ignored on that
+ *  arm — TiDB has no protocol-byte envelope to name); PG goes through `pgProtocolJsonStringify(v, label)`,
+ *  whose `label` names the field in its error text on an unstorable-byte reject. */
+export const dialectProtocolJsonEncoder = (dialect) => dialect === "tidb" ? (v) => JSON.stringify(v) : pgProtocolJsonStringify;
 //# sourceMappingURL=sql-driver.js.map

package/dist/prompts-domain-validate.js

@@ -16,9 +16,9 @@ import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { verifyPromptArtifact } from "@sema-agent/core";
+import { SHA256_DIGEST_RE } from "./digest-form.js";
 const ID_RE = /^[a-z0-9][a-z0-9/._-]*$/; // core assemble 同形(≤128、非 core/ 前缀在下面单查)
 const SLOTS = new Set(["identity", "scenario", "behavior"]);
-const HASH_RE = /^sha256:[0-9a-f]{64}$/;
 function declarationIssue(d, where) {
     if (d === null || typeof d !== "object")
         return `${where}: declaration is not an object`;
@@ -35,7 +35,7 @@ function declarationIssue(d, where) {
     // contentHash?),hash 缺席/被 core 丢弃(错值)后**同长度文本编辑不改 artifactDigest=不重 pin**,
     // 恰是撤 restart 臂所依赖的审计不变量被击穿。center 链路恒逐 section 铸([1065]),正常路径零影响;
     // 这里拒的是坏发布/被改载荷(整拒候选,LKG/内置继续服务)。
-    if (typeof o.contentHash !== "string" || !HASH_RE.test(o.contentHash))
+    if (typeof o.contentHash !== "string" || !SHA256_DIGEST_RE.test(o.contentHash))
         return `${where}: contentHash is required (sha256:<64hex> — the epoch declaration axis needs it for byte-level change detection)`;
     const expected = `sha256:${createHash("sha256").update(o.text).digest("hex")}`;
     if (o.contentHash !== expected)
@@ -53,7 +53,7 @@ export function validateCenterPrompts(raw) {
     const p = raw;
     if (typeof p.packId !== "string" || !/^center:[0-9a-f]{12}$/.test(p.packId))
         return { ok: false, error: "bad packId form (center:<digest12>)" };
-    if (typeof p.contentDigest !== "string" || !HASH_RE.test(p.contentDigest))
+    if (typeof p.contentDigest !== "string" || !SHA256_DIGEST_RE.test(p.contentDigest))
         return { ok: false, error: "bad contentDigest form" };
     // 发版复审 F2/F4 两条硬化:
     //  - 数组内 id 必须唯一(core composer 对 duplicate section id 是 THROW——独立判形查不出对撞,必须

package/dist/runs.d.ts

@@ -7,6 +7,7 @@ import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
 import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
+import type { VerifyRoundsSpec } from "./http/verify-rounds.js";
 /**
  * stoppedBy (core 1.252): a service cancel is a USER stop — mark the run's still-running background
  * children BEFORE core's teardown reaps them (bare abort = attribution falls back to "system"; core's own
@@ -201,10 +202,7 @@ export declare function evictIfConflict(runner: Runner, sessionId: string | unde
  * only — a suspended run is steered durably via the checkpoint's `setPendingSteer` instead, and only the
  * plain-stream path holds a steerable stream (the verify/cascade branches return a result, not a stream).
  */
-export declare function runInBackground(runner: Runner, spec: TaskSpec, runStore: RunStore, taskId: string, metrics?: Metrics, principal?: string, verify?: {
-    maxRounds: number;
-    costCeilingMicroUsd?: number;
-}, // 快审 F1:number 参升整对象——cost 顶随传
+export declare function runInBackground(runner: Runner, spec: TaskSpec, runStore: RunStore, taskId: string, metrics?: Metrics, principal?: string, verify?: VerifyRoundsSpec, // 快审 F1:number 参升整对象——cost 顶随传
 cascade?: CascadeConfig, instrumentDegenerate?: (result: TaskResult) => void, planCacheProbe?: {
     record: (scope: string | undefined, objective: string, completed: boolean) => void;
 }, persistThinking?: boolean, inflight?: Map<string, AbortController>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, 

package/dist/security.d.ts

@@ -194,6 +194,17 @@ export declare const PRINCIPAL_MAX_LENGTH = 190;
 export declare const RESERVED_PRINCIPALS: readonly string[];
 export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
 export declare function assertPrincipalShape(principal: string): void;
+/** The checkpoint `scope` column's single-user/anonymous sentinel — the same "_" documented above
+ *  ({@link RESERVED_PRINCIPALS}) as the checkpoint/sendfile/resource-suspend scope family's shared value.
+ *  Single attested constant + codec pair (naming precedent: {@link SENDFILE_SINGLE_USER_SCOPE} in
+ *  ./plugins/send-file-ledger.js) so every checkpoint scope read/write goes through one place instead of
+ *  each call site re-deriving the "_" ⇄ no-principal mapping inline. */
+export declare const CHECKPOINT_PUBLIC_SCOPE: "_";
+/** Encode a principal (or none) as the checkpoint `scope` column value. */
+export declare const encodeCheckpointScope: (principal: string | null | undefined) => string;
+/** Decode a checkpoint `scope` column value back to a principal — {@link CHECKPOINT_PUBLIC_SCOPE} maps to
+ *  `undefined` (no principal), everything else passes through verbatim. */
+export declare const decodeCheckpointScope: (scope: string) => string | undefined;
 /** Read the authenticated principal from the trusted header. Never from the body. */
 export declare function principalFrom(req: IncomingMessage, config: ServiceConfig): string | undefined;
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only

package/dist/security.js

@@ -256,6 +256,17 @@ export function assertPrincipalShape(principal) {
         throw new HttpError(400, `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`, { code: "principal_too_long" });
     }
 }
+/** The checkpoint `scope` column's single-user/anonymous sentinel — the same "_" documented above
+ *  ({@link RESERVED_PRINCIPALS}) as the checkpoint/sendfile/resource-suspend scope family's shared value.
+ *  Single attested constant + codec pair (naming precedent: {@link SENDFILE_SINGLE_USER_SCOPE} in
+ *  ./plugins/send-file-ledger.js) so every checkpoint scope read/write goes through one place instead of
+ *  each call site re-deriving the "_" ⇄ no-principal mapping inline. */
+export const CHECKPOINT_PUBLIC_SCOPE = "_";
+/** Encode a principal (or none) as the checkpoint `scope` column value. */
+export const encodeCheckpointScope = (principal) => principal ?? CHECKPOINT_PUBLIC_SCOPE;
+/** Decode a checkpoint `scope` column value back to a principal — {@link CHECKPOINT_PUBLIC_SCOPE} maps to
+ *  `undefined` (no principal), everything else passes through verbatim. */
+export const decodeCheckpointScope = (scope) => (scope === CHECKPOINT_PUBLIC_SCOPE ? undefined : scope);
 /** Read the authenticated principal from the trusted header. Never from the body. */
 export function principalFrom(req, config) {
     if (!config.principalHeader)

package/dist/session-sync.d.ts

@@ -15,10 +15,21 @@
  */
 import type { StoreBackend } from "./plugins/store-backend.js";
 import { type SyncRelation } from "./session-sync-kernel.js";
-import type { SessionTreeEntry, SessionRulesRecord } from "@sema-agent/core";
+import type { SessionTreeEntry, SessionRulesRecord, FileSnapshotResult } from "@sema-agent/core";
 /** A blob getter: content-addressed bytes for a sha256 hash, or `undefined` if the source can't supply them.
  *  Returned by {@link exportSession} (closes over the source store), consumed by {@link importSession}. */
 export type BlobGetter = (hash: string) => Promise<Uint8Array | undefined>;
+/** The snapshot-import capability face of a `FileSnapshotStore` — signature verbatim = the authoritative
+ *  implementation, `FileSnapshotStoreSql.importManifest` (src/plugins/file-snapshot-store-sql.ts:201). */
+export interface FileSnapshotImportFace {
+    importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: BlobGetter): Promise<FileSnapshotResult>;
+}
+/** Single-point capability probe (design/158 R7): does `fs` carry the optional `importManifest` snapshot-import
+ *  seam? Returns the bound method (never a naked function reference — `this` inside `importManifest` must resolve
+ *  to `fs`, exactly like `asServiceDeps`'s other capability-probe-then-bind authorities) or `undefined` when the
+ *  seam is absent (an older/in-memory dev store). Callers gate on the RETURN VALUE, not a separate `typeof` check,
+ *  so there is exactly one place that knows the shape of the probe. */
+export declare function fileSnapshotImportFace(fs: unknown): FileSnapshotImportFace | undefined;
 export { stagingIdFor, STAGING_ID_MARKER, realIdOfStaging, classifySyncRelationship, classifySyncRelationshipByIds, SyncConflictError } from "./session-sync-kernel.js";
 export type { StagingHandle, ImportStagingStore, SyncRelation } from "./session-sync-kernel.js";
 /**

package/dist/session-sync.js

@@ -1,6 +1,17 @@
 import { identicalIdsAlsoIdenticalContent } from "./session-sync-content.js";
 import { classifySyncRelationship, SyncConflictError } from "./session-sync-kernel.js";
 import { validateEntriesForImport, normalizeRules, stripRev } from "@sema-agent/core";
+/** Single-point capability probe (design/158 R7): does `fs` carry the optional `importManifest` snapshot-import
+ *  seam? Returns the bound method (never a naked function reference — `this` inside `importManifest` must resolve
+ *  to `fs`, exactly like `asServiceDeps`'s other capability-probe-then-bind authorities) or `undefined` when the
+ *  seam is absent (an older/in-memory dev store). Callers gate on the RETURN VALUE, not a separate `typeof` check,
+ *  so there is exactly one place that knows the shape of the probe. */
+export function fileSnapshotImportFace(fs) {
+    const candidate = fs?.importManifest;
+    if (typeof candidate !== "function")
+        return undefined;
+    return { importManifest: candidate.bind(fs) };
+}
 // ── PURE KERNEL moved to ./session-sync-kernel.ts (design/158 A2) ─────────────────────────────────────────────
 // The §7 relation classifier (classifySyncRelationship[ByIds]), the staging-id scheme (stagingIdFor /
 // STAGING_ID_MARKER / realIdOfStaging), the StagingHandle / ImportStagingStore contracts and SyncConflictError
@@ -196,7 +207,8 @@ export async function exportSessionManifest(sessionId, srcBackend) {
 export async function importSession(bundle, getBlob, dstBackend, importingPrincipal, opts) {
     const sessionId = bundle.sessionId;
     const fs = dstBackend.fileSnapshot();
-    const canImportSnapshots = typeof fs.importManifest === "function";
+    const importFace = fileSnapshotImportFace(fs);
+    const canImportSnapshots = importFace !== undefined;
     // ── §7 classification gate, BEFORE any write ───────────────────────────────────────────────────────────────
     // Read the destination's CURRENT entry log and classify the relationship (sound entry-id set comparison). A fork or
     // a stale source would lose dst history → refuse with a typed 409 unless the caller explicitly resolved overwrite-dst.
@@ -290,8 +302,8 @@ export async function importSession(bundle, getBlob, dstBackend, importingPrinci
     //    written (the commit point is inside importEntries, step ②), so the dst stays clean (only collectable orphans).
     let snapshotsImported = 0;
     let snapshotsSkipped = 0;
-    if (canImportSnapshots) {
-        const importManifest = fs.importManifest.bind(fs);
+    if (importFace) {
+        const importManifest = importFace.importManifest;
         for (const snap of bundle.snapshots) {
             const r = await importManifest(sessionId, snap.key, new Map(snap.manifest), getBlob);
             if (!r.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "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",