@sema-agent/settings-schema 10.1.0 → 11.0.0

package/dist/safety-merge-spec.js

@@ -1,10 +1,10 @@
 /**
  * #14 SAFETY MERGE-SPEC — the ONE machine-readable per-category merge/enforcement table that every settings
- * resolver (TOC shell-adapter + TOB center/service) reads, so they never re-implement (and drift on) the merge
+ * resolver (TOC shell-adapter + TOB web-admin/service) reads, so they never re-implement (and drift on) the merge
  * law. This formalizes settings-core's v2-design §3 merge-spec into a published-data contract; the SEMANTIC
- * author is settings-core, center maintains the formalized artifact here (registry-core), the axis VALUE domains
+ * author is settings-core, web-admin maintains the formalized artifact here (this package), the axis VALUE domains
  * are core's (@sema-agent/core SAFETY_AXIS_VOCABULARY — validated by a dev-only conformance test, never a runtime
- * import). Each consumer keeps its OWN key→category map (client's SemaSettings KEY_CONTRACTS, center's
+ * import). Each consumer keeps its OWN key→category map (client's SemaSettings KEY_CONTRACTS, web-admin's
  * config-field→category map); THIS file is only the shared category spec they all cite — no third copy of the law.
  *
  * Per-category behavior is fully determined by `mergeShape` + `minTrust` + `tighten` + `enforcement` + `fail` — and,
@@ -118,14 +118,16 @@ export const SpecEnforcement = z.enum(["gate", "server", "resolver", "client"]);
  *  enforcement on NON-secret keys (additive merges like mcpServers/rules/env); `gate`/`server`/secret → CLOSED. */
 export const FailMode = z.enum(["closed", "open"]);
 /** The monotone tighten-only direction for a category (which way is "stricter"). `enumRank.order` lists values
- *  from LOOSEST→STRICTEST; `boolStricter.strict` is the bool value that is the tighter one; `setNarrower` = a
- *  subset is tighter; `policyDenyWins` = deny beats allow; `none` = not rank-tightenable (replace / conflict-reject). */
+ *  from LOOSEST→STRICTEST — the category's whole vocabulary: a word outside it is refused, and a ONE-word order (11.0.0:
+ *  `shellGate`, whose engine vocabulary is the single floor word) is the degenerate rank where the only merge is identity;
+ *  `boolStricter.strict` is the bool value that is the tighter one; `setNarrower` = a subset is tighter; `policyDenyWins` =
+ *  deny beats allow; `none` = not rank-tightenable (replace / conflict-reject). */
 export const TightenRule = z.discriminatedUnion("rule", [
     z.object({ rule: z.literal("none") }),
     z.object({ rule: z.literal("policyDenyWins") }),
     z.object({ rule: z.literal("setNarrower") }),
     z.object({ rule: z.literal("boolStricter"), strict: z.boolean() }),
-    z.object({ rule: z.literal("enumRank"), order: z.array(z.string()).min(2) }),
+    z.object({ rule: z.literal("enumRank"), order: z.array(z.string()).min(1) }),
 ]);
 export const MergeCategorySpec = z.object({
     mergeShape: MergeShape,
@@ -158,15 +160,17 @@ export const SAFETY_MERGE_SPEC = {
             ask: { direction: "tighten", minTrust: "local" },
         },
     },
-    // [3759] order covers the FULL shell-addressable mode vocabulary — a word missing here is not "unknown", it
-    // makes every two-layer merge containing it hit the out-of-vocabulary reject arm (the whole bundle used to be
-    // dropped; shells now reject per-unit, but the semantic fix is a complete rank). Rank anchors (server
-    // task-settings.ts translation): bypass ⇒ shellGate off; auto ⇒ classify with classifier auto-release over ANY
-    // benign ask (⊇ acceptEdits' edits-only auto-allow); dontAsk = every would-ask → deny (allow rules still pass,
-    // tighter than default, looser than plan's handsReadOnly).
+    // Order covers the FULL shell-addressable mode vocabulary — a word missing here is not "unknown", it makes every
+    // two-layer merge containing it hit the out-of-vocabulary reject arm (the whole bundle used to be dropped; shells now
+    // reject per-unit, but the semantic fix is a complete rank). Rank anchors (the engine's mode arbitration): bypass
+    // releases every releasable ask; auto hands them to the classifier, which may auto-release ANY benign ask (⊇
+    // acceptEdits' edits-only auto-allow); dontAsk = every would-ask → deny (allow rules still pass, tighter than default,
+    // looser than plan's handsReadOnly).
     permissionMode: { mergeShape: "replace", minTrust: "global", tighten: { rule: "enumRank", order: ["bypassPermissions", "auto", "acceptEdits", "default", "dontAsk", "plan"] }, enforcement: "gate", fail: "closed", seam: "derive → toolPolicy / onAsk / handsReadOnly (§6.4); bypass = launch-flag only + MANAGED kill-switch" },
     handsReadOnly: { mergeShape: "replace", minTrust: "global", tighten: { rule: "boolStricter", strict: true }, enforcement: "gate", fail: "closed", seam: "handsReadOnly" },
-    shellGate: { mergeShape: "replace", minTrust: "global", tighten: { rule: "enumRank", order: ["off", "classify", "always"] }, enforcement: "gate", fail: "closed", seam: "shellGate", coreAxis: "shellGate" },
+    // The engine's shell floor has ONE word, `"always"` (the operator mandates a per-call confirmation for every shell command);
+    // the earlier `off` / `classify` are refused at the engine's door, so a layer carrying either is out of vocabulary here too.
+    shellGate: { mergeShape: "replace", minTrust: "global", tighten: { rule: "enumRank", order: ["always"] }, enforcement: "gate", fail: "closed", seam: "shellGate", coreAxis: "shellGate" },
     approver: { mergeShape: "replace", minTrust: "global", tighten: { rule: "none" }, enforcement: "gate", fail: "closed", seam: "onAsk (conflict → reject)" },
     // S-59 件八 — member-level admission for the sandbox category (the shell's temporary "which sub-key counts
     // as tightening" table lifts upstream; its gate keeps only the VALUE-pole half as executing detail).
@@ -227,7 +231,7 @@ export const SAFETY_MERGE_SPEC = {
     memoryScopes: { mergeShape: "concat", minTrust: "global", tighten: { rule: "none" }, enforcement: "client", fail: "open", seam: "MemoryStore" },
     autoCompaction: { mergeShape: "replace", minTrust: "session", tighten: { rule: "none" }, enforcement: "client", fail: "open", seam: "compaction config" },
     ui: { mergeShape: "replace", minTrust: "local", tighten: { rule: "none" }, enforcement: "client", fail: "open", seam: "shell-only (theme/keybindings/statusLine) — never touches the engine" },
-    org: { mergeShape: "replace", minTrust: "managed", tighten: { rule: "none" }, enforcement: "server", fail: "closed", seam: "config-center → governanceBaseline (SSO/SCIM/audit/budget, TOB-only)" },
+    org: { mergeShape: "replace", minTrust: "managed", tighten: { rule: "none" }, enforcement: "server", fail: "closed", seam: "web-admin → governanceBaseline (SSO/SCIM/audit/budget, TOB-only)" },
 };
 /** Own-property table lookup. The category union is compile-time only; a JavaScript or deserialized caller can
  *  hand in `"__proto__"` / `"constructor"` / `"toString"`, which a bare index resolves through Object.prototype

package/dist/scheduler-lifetime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 包内私有(不进主桶):调度记录「是不是会话链上的记录」的**一只**读法 —— `lifetime === "session"`;其余(含缺席)一律是 durable。
+ * 读口的过期清理(`parseSchedulerStore`)与一次性迁移 SS-M3 的 durable 键重铸读同一只,两处对同一条记录不可能给出两种答案。
+ */
+export declare function isSessionLifetime(record: object): boolean;

package/dist/scheduler-lifetime.js

@@ -0,0 +1,7 @@
+/**
+ * 包内私有(不进主桶):调度记录「是不是会话链上的记录」的**一只**读法 —— `lifetime === "session"`;其余(含缺席)一律是 durable。
+ * 读口的过期清理(`parseSchedulerStore`)与一次性迁移 SS-M3 的 durable 键重铸读同一只,两处对同一条记录不可能给出两种答案。
+ */
+export function isSessionLifetime(record) {
+    return record.lifetime === "session";
+}

package/dist/scheduler-store-migration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 一次性迁移 **SS-M3**(调度店 durable 键)的改写步 —— 包内私有,由 `./one-time-migrations` 以 `migrateSchedulerRecords` 再导出;
+ * `parseSchedulerStore` 在读时调它(lazy-on-read,登记在迁移表里的唯一读时改写;窗关随迁移族删)。单拆成叶子是为了让轻量的
+ * `./scheduler-store` 契约不把整套域 schema 拉进来。
+ *
+ * 规则(= 改写前每次 parse 都在做的生效读法,零语义变):`lifetime` 不是 `"session"` 的行(缺席 = durable)按 durable 铸键
+ * `scope := principal ?? "default"`;`"session"` 行是会话链键,不碰。只认形:改写后的行判据自不满足 ⇒ 重跑恒等。
+ */
+import type { MigrationReceipt } from "./migration-receipt.js";
+import type { SchedulerRecord } from "./scheduler-store.js";
+export declare function migrateSchedulerRecords(records: readonly SchedulerRecord[]): {
+    records: SchedulerRecord[];
+    receipts: MigrationReceipt[];
+};

package/dist/scheduler-store-migration.js

@@ -0,0 +1,14 @@
+import { isSessionLifetime } from "./scheduler-lifetime.js";
+export function migrateSchedulerRecords(records) {
+    const receipts = [];
+    const out = records.map((r, index) => {
+        if (isSessionLifetime(r))
+            return r;
+        const want = r.principal ?? "default";
+        if (r.scope === want)
+            return r;
+        receipts.push({ migration: "SS-M3", document: "scheduler-store", path: [index, "scope"], appliedAs: "rewritten" });
+        return { ...r, scope: want };
+    });
+    return { records: out, receipts };
+}

package/dist/scheduler-store-node.d.ts

@@ -1,12 +1,13 @@
-import { type SchedulerRecord, type SchedulerStore } from './scheduler-store.js';
+import { type SchedulerParseWarning, type SchedulerReadOptions, type SchedulerRecord, type SchedulerStore, type SchedulerStoreRead } from './scheduler-store.js';
 /**
- * Load the durable store. A MISSING file (ENOENT) ⇒ `[]` (fail-soft, first-run/never-written case); any OTHER
+ * Load the durable store. A MISSING file (ENOENT) ⇒ no records, no warnings (first-run/never-written case); any OTHER
  * read failure (EACCES/EIO/EISDIR/…) RETHROWS — only absence means "empty", not "unreadable for any reason"
  * (a permissions/IO fault silently treated as [] would let a caller-side save() overwrite real on-disk data with
- * an empty store). The pure parser drops corrupt individual records and preserves well-formed ones
- * (forward-compatible) — that degradation stays scoped to malformed CONTENT, not to read failures.
+ * an empty store). Content the parser could not read verbatim comes back in `warnings` ({@link parseSchedulerStore});
+ * a whole file that is not a JSON array reads as zero records + `unreadable-file` — NOT as an empty store (writers must go
+ * through {@link mutateSchedulerStore}, which refuses to write over it).
  */
-export declare function loadSchedulerStore(path: string): SchedulerRecord[];
+export declare function loadSchedulerStore(path: string, opts: SchedulerReadOptions): SchedulerStoreRead;
 /**
  * Persist ATOMICALLY: `mkdir -p` the parent, write a uniquely-named `.tmp` sibling (mode 0o600 — owner-only, the
  * records may carry principal/session identifiers), then `rename` over the target (atomic on POSIX, so a
@@ -19,10 +20,14 @@ export declare function saveSchedulerStore(path: string, records: SchedulerRecor
  * 的**活对象** ⇒ 按本组工厂命名法(`build*` 出纯数据、`create*` 出活对象)该叫 `create*`;2.0.0 那次照人眼
  * 改只改到了 `createSiblingResolver`,漏了这处 —— 现在由 `test/factory-naming-4.0.0.test.ts` 的门④ 机器看着。
  * 消费方改调 `createFileSchedulerStore`(改名是硬 breaking:消费方的 tsc 红 / 运行期 undefined 就是通知本身)。 */
-export declare function createFileSchedulerStore(path: string): SchedulerStore;
+export declare function createFileSchedulerStore(path: string, opts: {
+    now: () => number;
+}): SchedulerStore;
 /** Outcome of {@link mutateSchedulerStore}. `conflict_exhausted` = a concurrent writer kept changing the file
- *  faster than the bounded replays; nothing was written on that final attempt (earlier attempts never wrote). */
-export type SchedulerStoreMutation = {
+ *  faster than the bounded replays; nothing was written on that final attempt (earlier attempts never wrote).
+ *  `unreadable_file` = the file on disk is not a JSON array: `fn` never ran and nothing was written (writing would replace
+ *  data this reader cannot read with `fn`'s output). Every outcome carries the `warnings` of the last base read. */
+export type SchedulerStoreMutation = ({
     ok: true;
     records: SchedulerRecord[];
     retries: number;
@@ -33,6 +38,11 @@ export type SchedulerStoreMutation = {
 } | {
     ok: false;
     reason: 'aborted';
+} | {
+    ok: false;
+    reason: 'unreadable_file';
+}) & {
+    warnings: SchedulerParseWarning[];
 };
 /**
  * The ONE cross-process mutation primitive for the shared scheduler store ([ref]①/② —
@@ -54,7 +64,12 @@ export type SchedulerStoreMutation = {
  * eliminate it (that would need an advisory lock protocol every writer joins; rejected for
  * stale-lock ops burden + win32 friction). `fn` re-runs on replay: side effects inside `fn` are a
  * caller bug.
+ *
+ * 11.0.0: this is the ONE write primitive every writer goes through (the naked load→save sequence is the lost-update race
+ * above). A base file that is not a JSON array ⇒ `unreadable_file`, no write. `nowMs` is the caller's clock (the read drops
+ * session-pinned records that went stale — see `parseSchedulerStore`).
  */
-export declare function mutateSchedulerStore(path: string, fn: (records: SchedulerRecord[]) => SchedulerRecord[] | null, opts?: {
+export declare function mutateSchedulerStore(path: string, fn: (records: SchedulerRecord[]) => SchedulerRecord[] | null, opts: {
+    nowMs: number;
     retries?: number;
 }): SchedulerStoreMutation;

package/dist/scheduler-store-node.js

@@ -1,6 +1,6 @@
 /**
  * @sema-agent/settings-schema/node — the Node filesystem BINDING of the scheduler-store contract. Split out of the
- * pure barrel (it pulls `node:fs`/`node:path`/`node:crypto`) per registry-core's browser-safe discipline. Both
+ * pure barrel (it pulls `node:fs`/`node:path`/`node:crypto`) per this package's browser-safe discipline. Both
  * the server-side writer and the TOC shell daemon import THIS for the on-disk store; the FORMAT lives in the
  * pure `./scheduler-store` contract, so there is one shape and no drift.
  *
@@ -11,21 +11,24 @@ import { dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { parseSchedulerStore, serializeSchedulerStore } from './scheduler-store.js';
 /**
- * Load the durable store. A MISSING file (ENOENT) ⇒ `[]` (fail-soft, first-run/never-written case); any OTHER
+ * Load the durable store. A MISSING file (ENOENT) ⇒ no records, no warnings (first-run/never-written case); any OTHER
  * read failure (EACCES/EIO/EISDIR/…) RETHROWS — only absence means "empty", not "unreadable for any reason"
  * (a permissions/IO fault silently treated as [] would let a caller-side save() overwrite real on-disk data with
- * an empty store). The pure parser drops corrupt individual records and preserves well-formed ones
- * (forward-compatible) — that degradation stays scoped to malformed CONTENT, not to read failures.
+ * an empty store). Content the parser could not read verbatim comes back in `warnings` ({@link parseSchedulerStore});
+ * a whole file that is not a JSON array reads as zero records + `unreadable-file` — NOT as an empty store (writers must go
+ * through {@link mutateSchedulerStore}, which refuses to write over it).
  */
-export function loadSchedulerStore(path) {
+export function loadSchedulerStore(path, opts) {
+    let text;
     try {
-        return parseSchedulerStore(readFileSync(path, 'utf-8'));
+        text = readFileSync(path, 'utf-8');
     }
     catch (e) {
         if (e.code === 'ENOENT')
-            return [];
+            return { records: [], warnings: [] };
         throw e;
     }
+    return parseSchedulerStore(text, opts);
 }
 /**
  * Persist ATOMICALLY: `mkdir -p` the parent, write a uniquely-named `.tmp` sibling (mode 0o600 — owner-only, the
@@ -44,9 +47,9 @@ export function saveSchedulerStore(path, records) {
  * 的**活对象** ⇒ 按本组工厂命名法(`build*` 出纯数据、`create*` 出活对象)该叫 `create*`;2.0.0 那次照人眼
  * 改只改到了 `createSiblingResolver`,漏了这处 —— 现在由 `test/factory-naming-4.0.0.test.ts` 的门④ 机器看着。
  * 消费方改调 `createFileSchedulerStore`(改名是硬 breaking:消费方的 tsc 红 / 运行期 undefined 就是通知本身)。 */
-export function createFileSchedulerStore(path) {
+export function createFileSchedulerStore(path, opts) {
     return {
-        load: () => loadSchedulerStore(path),
+        load: () => loadSchedulerStore(path, { nowMs: opts.now() }),
         save: (records) => saveSchedulerStore(path, records),
     };
 }
@@ -70,9 +73,13 @@ export function createFileSchedulerStore(path) {
  * eliminate it (that would need an advisory lock protocol every writer joins; rejected for
  * stale-lock ops burden + win32 friction). `fn` re-runs on replay: side effects inside `fn` are a
  * caller bug.
+ *
+ * 11.0.0: this is the ONE write primitive every writer goes through (the naked load→save sequence is the lost-update race
+ * above). A base file that is not a JSON array ⇒ `unreadable_file`, no write. `nowMs` is the caller's clock (the read drops
+ * session-pinned records that went stale — see `parseSchedulerStore`).
  */
 export function mutateSchedulerStore(path, fn, opts) {
-    const maxRetries = Math.max(0, opts?.retries ?? 5);
+    const maxRetries = Math.max(0, opts.retries ?? 5);
     const rawOf = () => {
         try {
             return readFileSync(path, 'utf-8');
@@ -86,16 +93,19 @@ export function mutateSchedulerStore(path, fn, opts) {
     };
     for (let attempt = 0;; attempt++) {
         const baseRaw = rawOf();
-        const records = baseRaw === null ? [] : parseSchedulerStore(baseRaw);
-        const next = fn(records);
+        const base = baseRaw === null ? { records: [], warnings: [] } : parseSchedulerStore(baseRaw, { nowMs: opts.nowMs });
+        const { warnings } = base;
+        if (warnings.some((w) => w.kind === 'unreadable-file'))
+            return { ok: false, reason: 'unreadable_file', warnings };
+        const next = fn(base.records);
         if (next === null)
-            return { ok: false, reason: 'aborted' };
+            return { ok: false, reason: 'aborted', warnings };
         if (rawOf() !== baseRaw) {
             if (attempt >= maxRetries)
-                return { ok: false, reason: 'conflict_exhausted', retries: attempt };
+                return { ok: false, reason: 'conflict_exhausted', retries: attempt, warnings };
             continue; // a concurrent writer landed between our read and commit intent — replay on the new base
         }
         saveSchedulerStore(path, next);
-        return { ok: true, records: next, retries: attempt };
+        return { ok: true, records: next, retries: attempt, warnings };
     }
 }

package/dist/scheduler-store.d.ts

@@ -17,6 +17,7 @@
  * 🔴 `principal` is pinned by the writer from Runner-held ctx (never the model); persisted opaquely, passed
  * through to `runTask` unchanged by the daemon (no privilege escalation).
  */
+import type { MigrationReceipt } from './migration-receipt.js';
 /** A scheduled `when` — structurally identical to core `ScheduledIntent['when']`, inlined (contract stands alone). */
 export type SchedulerWhen = {
     kind: 'cron';
@@ -47,31 +48,63 @@ export interface SchedulerRecord {
 /**
  * The store ABSTRACTION the two sides depend on (writer saves, reader loads). The `@sema-agent/settings-schema/node`
  * file binding implements it; a server with a DB backend could implement it differently against the same shape.
+ * `load()` returns the records AND what the read did to them ({@link SchedulerStoreRead}) — there is no silent read.
  */
 export interface SchedulerStore {
-    load(): SchedulerRecord[];
+    load(): SchedulerStoreRead;
     save(records: SchedulerRecord[]): void;
 }
 /** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
 export declare function isSchedulerRecord(v: unknown): v is SchedulerRecord;
-/** Something {@link parseSchedulerStore} DID to the data it read, rather than reading it verbatim. `index` =
- *  the record's position in the parsed array (for correlating with the source file). Additive — passing
- *  `onWarning` is optional, and a new `kind` is an additive union member (a consumer with an exhaustive
- *  `switch` gains an arm to write).
- *   - `malformed-record`      — the record failed {@link isSchedulerRecord} and was dropped; `record` = the
- *                               raw (unvalidated) value, for diagnostics.
- *   - `durable-scope-rekeyed` — the durable-scope compat arm rewrote this row's `scope` (2.0.0; before that
- *                               the rewrite happened silently every parse). */
+/** 一条会话链上的记录过期多久算「永驻孤儿」:`lifetime: "session"` ∧ `sessionId` 在场 ∧ `nextRunMs` 已过去这么久 ⇒ 读口丢弃并告警(7 天)。 */
+export declare const STALE_SESSION_RECORD_MS: number;
+/** {@link parseSchedulerStore} 对它读到的数据**做了什么**(而不是逐字读)。闭集 —— 新 `kind` 是联合加员(穷举 `switch` 的消费方
+ *  会编译红,那就是通知)。`index` = 记录在原数组里的下标(对照源文件用)。
+ *   - `unreadable-file`      — 整份文件不是 JSON / 不是数组:读出零条记录。**不是**「空店」:{@link mutateSchedulerStore} 遇它拒写
+ *                              (否则下一次保存会把盘上那份读不懂的数据整份覆盖掉)。
+ *   - `malformed-record`     — 这一条没过 {@link isSchedulerRecord},丢弃;`record` = 原值(未校验,诊断用)。
+ *   - `stale-session-record` — 会话链上的记录(`lifetime: "session"` ∧ `sessionId` 在场)而 `nextRunMs` 已过去 ≥ {@link STALE_SESSION_RECORD_MS}:
+ *                              它的会话没走到收割(无常驻 daemon 的车道 / 崩溃),再留着就是永驻。丢弃,不另起写 —— 下一个写者落盘。
+ *                              **只认显式的 `"session"`**:`lifetime` 缺席读作 durable(与 SS-M3 同一只读法);durable 记录带着来源 sessionId
+ *                              是合法形,daemon 停机一周后的 cron 照样是用户的任务,不许当孤儿丢。
+ *   - `one-time-migration`   — 登记过窗的一次性迁移在读时改写了这一条(今天只有 SS-M3:durable 行按旧会话键存 ⇒ 重铸成
+ *                              `principal ?? "default"`);`receipt` 是迁移的收据(`./one-time-migrations` 的同一形)。 */
 export type SchedulerParseWarning = {
-    index: number;
+    kind: 'unreadable-file';
+    why: 'not-json' | 'not-an-array';
+} | {
     kind: 'malformed-record';
+    index: number;
     record: unknown;
 } | {
+    kind: 'stale-session-record';
+    index: number;
+    id: string;
+    sessionId: string;
+    nextRunMs: number;
+} | {
+    kind: 'one-time-migration';
     index: number;
-    kind: 'durable-scope-rekeyed';
-    from: string;
-    to: string;
+    receipt: MigrationReceipt;
 };
-export declare function parseSchedulerStore(text: string, onWarning?: (w: SchedulerParseWarning) => void): SchedulerRecord[];
+/** 一次读的结果:留下的记录 + 读时做过的每一件事。没有「静默模式」—— 告警恒随结果返回,调用方决定记到哪。 */
+export interface SchedulerStoreRead {
+    readonly records: SchedulerRecord[];
+    readonly warnings: SchedulerParseWarning[];
+}
+/** 读口的入参:`nowMs` 由调用方给(本包不读墙钟),判 {@link STALE_SESSION_RECORD_MS}。 */
+export interface SchedulerReadOptions {
+    readonly nowMs: number;
+}
+/**
+ * Parse the durable store from its serialized form. FORWARD-COMPATIBLE: well-formed records keep ALL their fields (incl.
+ * unknown future ones) so a newer writer's data survives an older reader's round-trip. Every deviation from a verbatim
+ * read comes back in `warnings` ({@link SchedulerParseWarning}) — 11.0.0 removed the silent mode (the warning callback
+ * used to be optional, and the default read paths never passed it, so corrupt records vanished without a trace).
+ *
+ * 读时改写只有一种:登记在一次性迁移表里、窗内存活的 SS-M3(`migrateSchedulerRecords`,lazy-on-read —— 不另起写,由下一个写者
+ * 落盘;另起一次写只会多一个竞争写者)。窗关后随迁移族一起删。
+ */
+export declare function parseSchedulerStore(text: string, opts: SchedulerReadOptions): SchedulerStoreRead;
 /** Serialize the store to its canonical on-disk form (stable, pretty JSON). The WRITE half of the format contract. */
 export declare function serializeSchedulerStore(records: SchedulerRecord[]): string;

package/dist/scheduler-store.js

@@ -1,22 +1,5 @@
-/**
- * @sema-agent/settings-schema/scheduler-store — the PURE, dep-free CONTRACT for the self-wake scheduler store
- * (R7 自唤醒). The shared seam between the WRITER (server-side `SchedulerCapability`, persists the model's
- * CronCreate/Sleep intents) and the READER (TOC shell `SchedulerDaemon`, fires due intents). One canonical
- * on-disk SHAPE + parse/serialize ⇒ the two independently-built sides never drift on the format.
- *
- * 🔴 Contract discipline (this is a third-party contract lib, not an impl dump):
- *   - ABSTRACT: this module is the type + the parse/serialize FORMAT + the `SchedulerStore` interface. It has
- *     ZERO runtime IO and ZERO deps (no `@sema-agent/*`, no `node:*`) so it lives in the browser-safe barrel.
- *     The concrete filesystem binding is `@sema-agent/settings-schema/node` (`loadSchedulerStore`/`saveSchedulerStore`).
- *   - EXTENSIBLE: `parseSchedulerStore` is FORWARD-COMPATIBLE — it validates only the required shape and
- *     PRESERVES unknown fields, so a newer writer can add fields without an older reader dropping them on
- *     round-trip. New optional `SchedulerRecord` fields are additive (no breaking change).
- *   - CONTRACTUAL: `when` is an inlined structural union kept byte-compatible with core `ScheduledIntent['when']`
- *     but NOT imported — the contract stands alone, independent of the engine.
- *
- * 🔴 `principal` is pinned by the writer from Runner-held ctx (never the model); persisted opaquely, passed
- * through to `runTask` unchanged by the daemon (no privilege escalation).
- */
+import { isSessionLifetime } from './scheduler-lifetime.js';
+import { migrateSchedulerRecords } from './scheduler-store-migration.js';
 /** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
 export function isSchedulerRecord(v) {
     if (typeof v !== 'object' || v === null)
@@ -35,63 +18,51 @@ export function isSchedulerRecord(v) {
         return typeof w.delaySec === 'number';
     return false;
 }
+/** 一条会话链上的记录过期多久算「永驻孤儿」:`lifetime: "session"` ∧ `sessionId` 在场 ∧ `nextRunMs` 已过去这么久 ⇒ 读口丢弃并告警(7 天)。 */
+export const STALE_SESSION_RECORD_MS = 7 * 24 * 60 * 60 * 1000;
 /**
- * Parse the durable store from its serialized form. FAIL-SOFT + FORWARD-COMPATIBLE: corrupt/non-array/non-JSON
- * ⇒ `[]`; malformed individual records are dropped (the store self-heals on next save); well-formed records keep
- * ALL their fields (incl. unknown future ones) so a newer writer's data survives an older reader's round-trip.
- * `onWarning` (optional, additive — mirrors the `FileConfigStore`/`EffectiveReadWarning` precedent): called once
- * per dropped record so a caller can surface the loss instead of it vanishing silently (C5/C6 — a dropped
- * record must leave a trace reachable by whoever can act on it).
- */
-/**
- * core 5.5.0 durable 键分叉的迁移半场([ref];server 裁 (a) 一次性迁移,拒读侧
- * 双键容忍窗)。旧铸键链 `sessionId ?? principal ?? taskId ?? "default"` 让 durable 行的隔离键随会话
- * 走——新会话新 sessionId ⇒ 旧 durable job 永远 not_found。core 5.5.0 起 durable 铸键=
- * `principal ?? "default"`;存量旧键行由**本层**在 parse 时重铸(纯函数,幂等:重写后判据自不满足)。
+ * Parse the durable store from its serialized form. FORWARD-COMPATIBLE: well-formed records keep ALL their fields (incl.
+ * unknown future ones) so a newer writer's data survives an older reader's round-trip. Every deviation from a verbatim
+ * read comes back in `warnings` ({@link SchedulerParseWarning}) — 11.0.0 removed the silent mode (the warning callback
+ * used to be optional, and the default read paths never passed it, so corrupt records vanished without a trace).
  *
- * 为什么放 parse 而不是 loader:`loadSchedulerStore` 与 `mutateSchedulerStore` 都各自经
- * `parseSchedulerStore`——归一放这里=两条读路径、两个读者(server 写侧 backend / shell daemon)
- * 单点同愈,无第二机制。盘面在下一次 save 收敛(读侧恒一致,不做读时写放大)。
- *
- * 窄读判据:`lifetime` 不在本契约的显式键上(server 写侧作为 forward-compat 字段随行),按未知
- * 字段窄读——`"session"` 行是会话链键,零触碰;其余(缺席=durable 默认)按 durable 归一。
- *
- * 落日(2.0.0):删除它 = **持久数据**面的破坏(仍按旧键存着的 durable 行会就此找不回),所以不能在
- * minor 上一删了事 —— 归下一个 MAJOR,按持久数据的规矩办(响亮拒收 + 一次性迁移)。在那之前,本版把
- * 这次重写从**静默**改成**出声**(`durable-scope-rekeyed`,带改写前后):关窗的前提是有人能证明它
- * 已经不再触发,而不是有人记得它还在。
+ * 读时改写只有一种:登记在一次性迁移表里、窗内存活的 SS-M3(`migrateSchedulerRecords`,lazy-on-read —— 不另起写,由下一个写者
+ * 落盘;另起一次写只会多一个竞争写者)。窗关后随迁移族一起删。
  */
-function normalizeDurableScope(r) {
-    if (r.lifetime === 'session')
-        return r;
-    const want = r.principal ?? 'default';
-    return r.scope === want ? r : { ...r, scope: want };
-}
-export function parseSchedulerStore(text, onWarning) {
+export function parseSchedulerStore(text, opts) {
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        return [];
+        return { records: [], warnings: [{ kind: 'unreadable-file', why: 'not-json' }] };
     }
     if (!Array.isArray(parsed))
-        return [];
-    if (!onWarning)
-        return parsed.filter(isSchedulerRecord).map(normalizeDurableScope);
-    const out = [];
+        return { records: [], warnings: [{ kind: 'unreadable-file', why: 'not-an-array' }] };
+    const warnings = [];
+    const kept = [];
+    const keptFrom = [];
     parsed.forEach((record, index) => {
         if (!isSchedulerRecord(record)) {
-            onWarning({ index, kind: 'malformed-record', record });
+            warnings.push({ kind: 'malformed-record', index, record });
             return;
         }
-        const normalized = normalizeDurableScope(record);
-        // 兼容臂真改写了这一行才出声(未改写时 normalizeDurableScope 返回同一个引用)。
-        if (normalized !== record)
-            onWarning({ index, kind: 'durable-scope-rekeyed', from: record.scope, to: normalized.scope });
-        out.push(normalized);
+        if (isSessionLifetime(record) && typeof record.sessionId === 'string' && record.sessionId !== '' && typeof record.nextRunMs === 'number' && opts.nowMs - record.nextRunMs >= STALE_SESSION_RECORD_MS) {
+            warnings.push({ kind: 'stale-session-record', index, id: record.id, sessionId: record.sessionId, nextRunMs: record.nextRunMs });
+            return;
+        }
+        kept.push(record);
+        keptFrom.push(index);
     });
-    return out;
+    const migrated = migrateSchedulerRecords(kept);
+    for (const receipt of migrated.receipts) {
+        // 收据的坐标是迁移入参(`kept`)里的下标;换回原数组下标(对照源文件),与其余告警同一套坐标。
+        const at = receipt.path[0];
+        const index = typeof at === 'number' ? (keptFrom[at] ?? at) : -1;
+        warnings.push({ kind: 'one-time-migration', index, receipt: { ...receipt, path: [index, ...receipt.path.slice(1)] } });
+    }
+    warnings.sort((a, b) => ('index' in a ? a.index : -1) - ('index' in b ? b.index : -1));
+    return { records: migrated.records, warnings };
 }
 /** Serialize the store to its canonical on-disk form (stable, pretty JSON). The WRITE half of the format contract. */
 export function serializeSchedulerStore(records) {

package/dist/secret-refs.d.ts

@@ -1,12 +1,12 @@
 /**
- * Secret-reference inventory (Phase-3 "密钥引用校验"). sema-registry stores only env-NAMEs, never secret
+ * Secret-reference inventory (Phase-3 "密钥引用校验"). web-admin stores only env-NAMEs, never secret
  * values (the ENV_NAME boundary). This collects EVERY env-NAME the effective config references, grouped by
  * name with where each is used — so an operator can audit "which env vars must each host/service provide?"
  * before a worker/model fails at runtime.
  *
- * Note: sema-registry can't verify a name actually EXISTS in a consumer's environment (that's the consumer's
+ * Note: web-admin can't verify a name actually EXISTS in a consumer's environment (that's the consumer's
  * own env). For workers, the reconciler already reports a missing one as a `SecretMissing` status condition
- * (surfaced on /fleet). This inventory is the center-side half — every referenced env-NAME, incl. the general
+ * (surfaced on /fleet). This inventory is web-admin-side half — every referenced env-NAME, incl. the general
  * `secretEnv` passthrough, so a rotation runbook built on it isn't blind to app-specific tokens.
  */
 import type { EffectiveConfig } from "./types.js";

package/dist/secret-refs.js

@@ -22,7 +22,7 @@ export function collectEnvRefs(eff) {
         for (const [key, envName] of Object.entries(w.runtime.execution?.secretRefs ?? {}))
             add(envName, "workers", `worker "${w.name}".runtime.execution.secretRefs.${key}`);
         // the general secretEnv passthrough also references env-NAMEs (worker-env.ts merges them) — include them
-        // so the rotation inventory isn't blind to app-specific tokens like OA_SERVICE_TOKEN→OA_CALLBACK_TOKEN.
+        // so the rotation inventory isn't blind to app-specific tokens like MY_APP_TOKEN→MY_APP_TOKEN_ENV.
         for (const [key, envName] of Object.entries(w.secretEnv ?? {}))
             add(envName, "workers", `worker "${w.name}".secretEnv.${key}`);
     }

package/dist/secret-scan.d.ts

@@ -1,28 +1,11 @@
-/**
- * 秘密扫描读的**归一化**,外加「URL 的 userinfo 就是凭据」那一只判定({@link carriesUserinfo})—— 包内私有模块(6.3.0):不进主 barrel、
- * 不进 `package.json` 的 `exports`,消费方拿不到。
- * 校验侧探测器 `containsSecretToken`(`./types`)只读 {@link percentLayers};展示侧脱敏器 `redactSecrets`(`./config-fns`)
- * 读 {@link secretScanForms}。展示侧的读法(边界读法、`+` 读法、「没走完」那一位)刻意不做公开契约:它们以后要随新发现的
- * 编码形调整,调整不该是契约变更(opus 独立腿 L7)。
- *
- * **单遍、零异常**(opus 独立腿 M1,对 6.2.0 的读路径 CPU 回归):6.2.0 起的宽容解码对每个 `%HH` 各 `try decodeURIComponent`,
- * 非 ASCII 的转义每个都抛一次异常(≈ 20–30 µs / 字节,同步阻塞);6.3.0 首稿又让探测器顺带算它不用的展示形。这里两处解码都
- * 不靠异常:单个转义的判据写成字符集(只有 ASCII 的 `%00`–`%7F` 单独解得开),转义串的判据写成 UTF-8 良构判定 ——
- * 结果与原来的 try/catch 逐字相同(`test/disclosable-identity-6.3.0.test.ts` 的两只冻结 oracle 钉着)。
- *
- * 本模块零 import(`./types` 引它,它不回引,不成环)。
- */
 /** How many percent-decoded layers a secret scan reads beyond the raw string (a multi-encoded `%2573%256B…` →
  *  `%73%6B…` → `sk-…`). Bounded → deterministic. */
 export declare const SECRET_SCAN_DECODE_LAYERS = 3;
-/** The raw string first, then up to {@link SECRET_SCAN_DECODE_LAYERS} tolerant percent-decoded layers, stopping at the first
- *  layer that decodes nothing — the forms the validation detector `containsSecretToken` reads, and nothing else. */
-export declare function percentLayers(text: string): readonly string[];
 /** What {@link secretScanForms} returns — plain data, no behavior. */
 export interface SecretScanForms {
     /** {@link percentLayers} of the text. */
     readonly percentLayers: readonly string[];
-    /** The forms the display-side redactor judges a whole string on: `percentLayers`, each layer's {@link boundaryReading}, and
+    /** The forms a string is judged on (write and display alike): `percentLayers`, each layer's {@link boundaryReading}, and
      *  each of those read the application/x-www-form-urlencoded way (`+` as a space); duplicates dropped, first seen first. */
     readonly forms: readonly string[];
     /** Normalization did not finish: the layer budget ran out while one more layer would still decode something. A caller that
@@ -30,10 +13,17 @@ export interface SecretScanForms {
      *  point, not an unfinished one: `%E4%B8%AD` stays as it is and is not flagged.) */
     readonly unresolved: boolean;
 }
-/** The display-side normalization — only `redactSecrets` (config-fns) calls it. */
+/** The normalization BOTH scanners read (11.0.0): the validation detector `containsSecretToken` (types) and the display redactor
+ *  `redactSecrets` (config-fns). */
 export declare function secretScanForms(text: string): SecretScanForms;
-/** 「URL 的 userinfo 就是凭据」的**唯一**判定(6.3.0,opus 腿 L1):username / password 任一在场即是。校验侧 `NON_SECRET_URL` 与 https
- *  插件源据此拒写(`./types`),身份面据此否决(`./config-fns` 的 `isDisclosableIdentity` —— `https://admin:hunter2@db…` /
- *  `postgres://svc:pw@h` 的字符全在身份白名单里)。串解析不成 URL ⇒ false:这只判定只说「一个 URL 带没带 userinfo」,
- *  不是 URL 的串不在它的射程里(无 scheme 的 `svc:pw@host` 解析成不透明路径,同样答 false —— 如实登记的边界)。 */
-export declare function carriesUserinfo(u: URL | string): boolean;
+/** 「URL 的 userinfo 就是凭据」的**唯一**判定(6.3.0 起;11.0.0 S-811 扩到自由文本):文本是带 userinfo 的 URL(URL 形判官
+ *  {@link httpUrlFlaws} 判出 `userinfo` 这一件 —— 层级式任意 scheme,`ssh://git@host` 只带用户名也算),或文本里某个 `@` 收尾的那一段
+ *  (从 `@` 向前到空白或上一个 `@`)是凭据对:
+ *   · authority 形 —— 段里最后一个 `//` 到 `@` 之间非空且不含 `/ ? #`(`jdbc:postgresql://svc:pw@…`、`//admin:pw@…`、`ssh://git@h`);
+ *   · 冒号形 —— 段里最后一个 `/ ? #` 之后的那一截是 `user:pw`(两侧非空),且 `@` 后紧跟主机字符(`admin:pw@db:5432/app`、`postgres:/svc:pw@h`)。
+ *  引号 / 尖括号 / 反引号**不**断段(它们可以在口令里)。单遍:每个字符至多被一次向前扫描读到(段以上一个 `@` 为界、互不重叠)⇒ 线性,
+ *  不用回溯正则(codex r1:扫描正则在 `;` × 4 万 + `@` 上要 10 s)。
+ *  读者:展示侧 `redactSecrets`(`./config-fns`)对空白分隔的候选段与归一化形各问一次 —— 自由文本出门面(坐标 / 错误句 / 主机名标签)与身份面
+ *  (`isDisclosableIdentity` 问的就是 `redactSecrets` 原样放不放行)同一条律。校验侧不读它:URL 座位的 userinfo 由 URL 形判官拒,自由文本写口
+ *  不因 userinfo 拒(契约未变)。负控:路径里的 `@`(`https://h/@scope/pkg`)、邮箱、`name@版本`、空 userinfo(`https://@h`)都不是。 */
+export declare function carriesUserinfo(text: string): boolean;