@sema-agent/settings-schema 1.0.0

package/dist/safety-merge-spec.d.ts

@@ -0,0 +1,327 @@
+/**
+ * #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
+ * 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
+ * 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
+ * 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`; a resolver
+ * reads this table and has NO per-key special-casing.
+ */
+import { z } from "zod";
+/** How values from different layers/principals combine for a category. */
+export declare const MergeShape: z.ZodEnum<["denyFirst", "replace", "runAll", "overrideByName", "concat"]>;
+export type MergeShape = z.infer<typeof MergeShape>;
+/** The MINIMUM trust tier a layer/principal must have to set this category (ascending trust). */
+export declare const MinTrust: z.ZodEnum<["local", "session", "project", "global", "managed"]>;
+export type MinTrust = z.infer<typeof MinTrust>;
+/** WHERE the category is enforced (STRENGTH) — MUST stay in lockstep with `EffectiveKey.enforcement` (types.ts).
+ *  gate=data-plane engine, server=control-plane/TOB boundary, resolver=merger correctness, client=UI only. */
+export declare const SpecEnforcement: z.ZodEnum<["gate", "server", "resolver", "client"]>;
+export type SpecEnforcement = z.infer<typeof SpecEnforcement>;
+/** Fail direction when enforcement can't be evaluated. fail-OPEN is allowed for `client` OR `resolver`
+ *  enforcement on NON-secret keys (additive merges like mcpServers/rules/env); `gate`/`server`/secret → CLOSED. */
+export declare const FailMode: z.ZodEnum<["closed", "open"]>;
+export type FailMode = z.infer<typeof FailMode>;
+/** 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). */
+export declare const TightenRule: z.ZodDiscriminatedUnion<"rule", [z.ZodObject<{
+    rule: z.ZodLiteral<"none">;
+}, "strip", z.ZodTypeAny, {
+    rule: "none";
+}, {
+    rule: "none";
+}>, z.ZodObject<{
+    rule: z.ZodLiteral<"policyDenyWins">;
+}, "strip", z.ZodTypeAny, {
+    rule: "policyDenyWins";
+}, {
+    rule: "policyDenyWins";
+}>, z.ZodObject<{
+    rule: z.ZodLiteral<"setNarrower">;
+}, "strip", z.ZodTypeAny, {
+    rule: "setNarrower";
+}, {
+    rule: "setNarrower";
+}>, z.ZodObject<{
+    rule: z.ZodLiteral<"boolStricter">;
+    strict: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    strict: boolean;
+    rule: "boolStricter";
+}, {
+    strict: boolean;
+    rule: "boolStricter";
+}>, z.ZodObject<{
+    rule: z.ZodLiteral<"enumRank">;
+    order: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    rule: "enumRank";
+    order: string[];
+}, {
+    rule: "enumRank";
+    order: string[];
+}>]>;
+export type TightenRule = z.infer<typeof TightenRule>;
+export declare const MergeCategorySpec: z.ZodObject<{
+    mergeShape: z.ZodEnum<["denyFirst", "replace", "runAll", "overrideByName", "concat"]>;
+    minTrust: z.ZodEnum<["local", "session", "project", "global", "managed"]>;
+    tighten: z.ZodDiscriminatedUnion<"rule", [z.ZodObject<{
+        rule: z.ZodLiteral<"none">;
+    }, "strip", z.ZodTypeAny, {
+        rule: "none";
+    }, {
+        rule: "none";
+    }>, z.ZodObject<{
+        rule: z.ZodLiteral<"policyDenyWins">;
+    }, "strip", z.ZodTypeAny, {
+        rule: "policyDenyWins";
+    }, {
+        rule: "policyDenyWins";
+    }>, z.ZodObject<{
+        rule: z.ZodLiteral<"setNarrower">;
+    }, "strip", z.ZodTypeAny, {
+        rule: "setNarrower";
+    }, {
+        rule: "setNarrower";
+    }>, z.ZodObject<{
+        rule: z.ZodLiteral<"boolStricter">;
+        strict: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        strict: boolean;
+        rule: "boolStricter";
+    }, {
+        strict: boolean;
+        rule: "boolStricter";
+    }>, z.ZodObject<{
+        rule: z.ZodLiteral<"enumRank">;
+        order: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        rule: "enumRank";
+        order: string[];
+    }, {
+        rule: "enumRank";
+        order: string[];
+    }>]>;
+    enforcement: z.ZodEnum<["gate", "server", "resolver", "client"]>;
+    fail: z.ZodEnum<["closed", "open"]>;
+    /** The compile target / seam this category lands on (free text, for traceability). */
+    seam: z.ZodString;
+    /** When the category's VALUE domain is core's, the cited `SAFETY_AXIS_VOCABULARY` dimension (conformance-checked). */
+    coreAxis: z.ZodOptional<z.ZodEnum<["toolEffect", "egress", "irreversibility", "safetyAxis", "severity", "shellGate", "permissionDecision"]>>;
+}, "strip", z.ZodTypeAny, {
+    enforcement: "gate" | "server" | "resolver" | "client";
+    mergeShape: "concat" | "replace" | "denyFirst" | "runAll" | "overrideByName";
+    minTrust: "local" | "session" | "global" | "project" | "managed";
+    tighten: {
+        rule: "none";
+    } | {
+        rule: "policyDenyWins";
+    } | {
+        rule: "setNarrower";
+    } | {
+        strict: boolean;
+        rule: "boolStricter";
+    } | {
+        rule: "enumRank";
+        order: string[];
+    };
+    fail: "closed" | "open";
+    seam: string;
+    coreAxis?: "permissionDecision" | "toolEffect" | "egress" | "irreversibility" | "safetyAxis" | "severity" | "shellGate" | undefined;
+}, {
+    enforcement: "gate" | "server" | "resolver" | "client";
+    mergeShape: "concat" | "replace" | "denyFirst" | "runAll" | "overrideByName";
+    minTrust: "local" | "session" | "global" | "project" | "managed";
+    tighten: {
+        rule: "none";
+    } | {
+        rule: "policyDenyWins";
+    } | {
+        rule: "setNarrower";
+    } | {
+        strict: boolean;
+        rule: "boolStricter";
+    } | {
+        rule: "enumRank";
+        order: string[];
+    };
+    fail: "closed" | "open";
+    seam: string;
+    coreAxis?: "permissionDecision" | "toolEffect" | "egress" | "irreversibility" | "safetyAxis" | "severity" | "shellGate" | undefined;
+}>;
+export type MergeCategorySpec = z.infer<typeof MergeCategorySpec>;
+/** The category spec. Keys = the unified settings categories both seats map their concrete keys/fields into.
+ *  Faithful to settings-core v2-design §3 (the semantic source of record). */
+export declare const SAFETY_MERGE_SPEC: {
+    readonly permissions: {
+        readonly mergeShape: "denyFirst";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "policyDenyWins";
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "toolPolicy + deny-narrowing (SessionPolicyStore)";
+        readonly coreAxis: "permissionDecision";
+    };
+    readonly permissionMode: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "enumRank";
+            readonly order: ["bypassPermissions", "auto", "acceptEdits", "default", "dontAsk", "plan"];
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "derive → toolPolicy / onAsk / handsReadOnly (§6.4); bypass = launch-flag only + MANAGED kill-switch";
+    };
+    readonly handsReadOnly: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "boolStricter";
+            readonly strict: true;
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "handsReadOnly";
+    };
+    readonly shellGate: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "enumRank";
+            readonly order: ["off", "classify", "always"];
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "shellGate";
+        readonly coreAxis: "shellGate";
+    };
+    readonly approver: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "onAsk (conflict → reject)";
+    };
+    readonly sandboxNetwork: {
+        readonly mergeShape: "denyFirst";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "setNarrower";
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "ExecutionEnv (fs+net) + sensitive-path";
+        readonly coreAxis: "egress";
+    };
+    readonly hooks: {
+        readonly mergeShape: "runAll";
+        readonly minTrust: "project";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "gate";
+        readonly fail: "closed";
+        readonly seam: "hooks (single source or adapter-composed)";
+    };
+    readonly mcpServers: {
+        readonly mergeShape: "overrideByName";
+        readonly minTrust: "project";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "resolver";
+        readonly fail: "open";
+        readonly seam: "spec.mcp + allowTools";
+    };
+    readonly rulesInstructions: {
+        readonly mergeShape: "concat";
+        readonly minTrust: "project";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "resolver";
+        readonly fail: "open";
+        readonly seam: "appendSystemPrompt / memory (GLOBAL→PROJECT→SESSION)";
+    };
+    readonly model: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "session";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "client";
+        readonly fail: "open";
+        readonly seam: "RoleSpec / TaskSpec.{model,thinking}";
+    };
+    readonly env: {
+        readonly mergeShape: "concat";
+        readonly minTrust: "project";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "resolver";
+        readonly fail: "open";
+        readonly seam: "NodeExecutionEnv.shellEnv (later layer overrides same name)";
+    };
+    readonly envSecret: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "resolver";
+        readonly fail: "closed";
+        readonly seam: "§7 secret-ref resolution";
+    };
+    readonly memoryScopes: {
+        readonly mergeShape: "concat";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "client";
+        readonly fail: "open";
+        readonly seam: "MemoryStore";
+    };
+    readonly autoCompaction: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "session";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "client";
+        readonly fail: "open";
+        readonly seam: "compaction config";
+    };
+    readonly ui: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "local";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "client";
+        readonly fail: "open";
+        readonly seam: "shell-only (theme/keybindings/statusLine) — never touches the engine";
+    };
+    readonly org: {
+        readonly mergeShape: "replace";
+        readonly minTrust: "managed";
+        readonly tighten: {
+            readonly rule: "none";
+        };
+        readonly enforcement: "server";
+        readonly fail: "closed";
+        readonly seam: "config-center → governanceBaseline (SSO/SCIM/audit/budget, TOB-only)";
+    };
+};
+export type SafetyMergeCategory = keyof typeof SAFETY_MERGE_SPEC;

package/dist/safety-merge-spec.js

@@ -0,0 +1,70 @@
+/**
+ * #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
+ * 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
+ * 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
+ * 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`; a resolver
+ * reads this table and has NO per-key special-casing.
+ */
+import { z } from "zod";
+/** How values from different layers/principals combine for a category. */
+export const MergeShape = z.enum(["denyFirst", "replace", "runAll", "overrideByName", "concat"]);
+/** The MINIMUM trust tier a layer/principal must have to set this category (ascending trust). */
+export const MinTrust = z.enum(["local", "session", "project", "global", "managed"]);
+/** WHERE the category is enforced (STRENGTH) — MUST stay in lockstep with `EffectiveKey.enforcement` (types.ts).
+ *  gate=data-plane engine, server=control-plane/TOB boundary, resolver=merger correctness, client=UI only. */
+export const SpecEnforcement = z.enum(["gate", "server", "resolver", "client"]);
+/** Fail direction when enforcement can't be evaluated. fail-OPEN is allowed for `client` OR `resolver`
+ *  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). */
+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) }),
+]);
+export const MergeCategorySpec = z.object({
+    mergeShape: MergeShape,
+    minTrust: MinTrust,
+    tighten: TightenRule,
+    enforcement: SpecEnforcement,
+    fail: FailMode,
+    /** The compile target / seam this category lands on (free text, for traceability). */
+    seam: z.string(),
+    /** When the category's VALUE domain is core's, the cited `SAFETY_AXIS_VOCABULARY` dimension (conformance-checked). */
+    coreAxis: z.enum(["toolEffect", "egress", "irreversibility", "safetyAxis", "severity", "shellGate", "permissionDecision"]).optional(),
+});
+/** The category spec. Keys = the unified settings categories both seats map their concrete keys/fields into.
+ *  Faithful to settings-core v2-design §3 (the semantic source of record). */
+export const SAFETY_MERGE_SPEC = {
+    permissions: { mergeShape: "denyFirst", minTrust: "global", tighten: { rule: "policyDenyWins" }, enforcement: "gate", fail: "closed", seam: "toolPolicy + deny-narrowing (SessionPolicyStore)", coreAxis: "permissionDecision" },
+    // [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).
+    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" },
+    approver: { mergeShape: "replace", minTrust: "global", tighten: { rule: "none" }, enforcement: "gate", fail: "closed", seam: "onAsk (conflict → reject)" },
+    sandboxNetwork: { mergeShape: "denyFirst", minTrust: "global", tighten: { rule: "setNarrower" }, enforcement: "gate", fail: "closed", seam: "ExecutionEnv (fs+net) + sensitive-path", coreAxis: "egress" },
+    hooks: { mergeShape: "runAll", minTrust: "project", tighten: { rule: "none" }, enforcement: "gate", fail: "closed", seam: "hooks (single source or adapter-composed)" },
+    mcpServers: { mergeShape: "overrideByName", minTrust: "project", tighten: { rule: "none" }, enforcement: "resolver", fail: "open", seam: "spec.mcp + allowTools" },
+    rulesInstructions: { mergeShape: "concat", minTrust: "project", tighten: { rule: "none" }, enforcement: "resolver", fail: "open", seam: "appendSystemPrompt / memory (GLOBAL→PROJECT→SESSION)" },
+    model: { mergeShape: "replace", minTrust: "session", tighten: { rule: "none" }, enforcement: "client", fail: "open", seam: "RoleSpec / TaskSpec.{model,thinking}" },
+    env: { mergeShape: "concat", minTrust: "project", tighten: { rule: "none" }, enforcement: "resolver", fail: "open", seam: "NodeExecutionEnv.shellEnv (later layer overrides same name)" },
+    envSecret: { mergeShape: "replace", minTrust: "global", tighten: { rule: "none" }, enforcement: "resolver", fail: "closed", seam: "§7 secret-ref resolution" },
+    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)" },
+};

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

@@ -0,0 +1,72 @@
+import { type SchedulerRecord, type SchedulerStore } from './scheduler-store.js';
+/**
+ * Load the durable store. A MISSING file (ENOENT) ⇒ `[]` (fail-soft, 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.
+ */
+export declare function loadSchedulerStore(path: string): SchedulerRecord[];
+/**
+ * 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
+ * concurrent reader never sees a partial file). Throws on IO failure (caller maps to a domain error).
+ */
+export declare function saveSchedulerStore(path: string, records: SchedulerRecord[]): void;
+/** A filesystem-backed {@link SchedulerStore} bound to a path (convenience for the daemon/backend constructors). */
+export declare function fileSchedulerStore(path: string): 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 = {
+    ok: true;
+    records: SchedulerRecord[];
+    retries: number;
+} | {
+    ok: false;
+    reason: 'conflict_exhausted';
+    retries: number;
+} | {
+    ok: false;
+    reason: 'aborted';
+};
+/**
+ * The ONE cross-process mutation primitive for the shared scheduler store (board [1001]①/[1003]② —
+ * server L1-2 + shell 对抗评审 F1 双向合流后的契约层统一原语). Every WRITER (engine backend, resident
+ * daemon fire/reap, session reap, sweeps) must go through this instead of hand-rolled
+ * load→filter→save — the naked sequence is a lost-update race: two writers load the same base
+ * array, mutate independently, and the later `save` silently reverts the earlier one.
+ *
+ * Optimistic concurrency, format-preserving (no envelope/sidecar/lock file):
+ *   1. read the RAW file text and keep it as the base witness (missing file ⇒ empty witness);
+ *   2. run `fn(records)` — MUST be pure/replayable; return the next records array, or `null` to
+ *      abort with no write (e.g. "nothing to do" discovered under the latest base);
+ *   3. re-read the raw text just before committing — if it no longer equals the witness, a
+ *      concurrent writer landed: REPLAY from step 1 (bounded by `retries`, default 5);
+ *   4. commit via the same tmp+rename atomic write as {@link saveSchedulerStore}.
+ *
+ * Honest limits (declared in [1003], server ACK'd): the witness-check→rename window is not zero —
+ * this SHRINKS the race from "the whole read-modify-write span" to microseconds, it does not
+ * 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.
+ */
+export declare function mutateSchedulerStore(path: string, fn: (records: SchedulerRecord[]) => SchedulerRecord[] | null, opts?: {
+    retries?: number;
+}): SchedulerStoreMutation;
+/** [1057]① prompts contentDigest(node 绑定;browser-safe 纯层不带 crypto):
+ *  canonical JSON(stableStringify 同姿势:键序稳定+深度护栏)全量 sha256,**非盐化**
+ *  ([1050]② operator 对账位——center 产、server 透传、core manifest 归因三方可独立复算)。
+ *  入参=下发形的 {sections, scenarioOverrides?}(packId/contentDigest 自身不入 hash)。 */
+export declare function promptsContentDigest(payload: {
+    sections: unknown;
+    scenarioOverrides?: unknown;
+}): {
+    contentDigest: string;
+    packId: string;
+    /** [1062]③ 顺带:逐 section 对 `text` 铸的 contentHash(与 core 1.315 校验语义同刻度=
+     *  sha256(text));元素无 string text 位=undefined。center 物化流程=先把这些写回
+     *  declaration.contentHash,再对含 hash 的终形铸整包 digest(本函数对入参原样铸,两步自洽)。 */
+    sectionHashes: Array<string | undefined>;
+};
+/** 逐 section 对账锚(core 1.315 `PromptTextDeclaration.contentHash` 同刻度):sha256(text)。 */
+export declare function sectionContentHash(text: string): string;

package/dist/scheduler-store-node.js

@@ -0,0 +1,119 @@
+/**
+ * @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
+ * 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.
+ *
+ * Store path = caller-supplied; both sides agree on `SEMA_CONFIG_DIR` → `~/.sema/scheduled_tasks.json`.
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes, createHash } from 'node:crypto';
+import { parseSchedulerStore, serializeSchedulerStore } from './scheduler-store.js';
+import { stableStringify } from './hash.js';
+/**
+ * Load the durable store. A MISSING file (ENOENT) ⇒ `[]` (fail-soft, 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.
+ */
+export function loadSchedulerStore(path) {
+    try {
+        return parseSchedulerStore(readFileSync(path, 'utf-8'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+}
+/**
+ * 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
+ * concurrent reader never sees a partial file). Throws on IO failure (caller maps to a domain error).
+ */
+export function saveSchedulerStore(path, records) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${randomBytes(6).toString('hex')}.tmp`;
+    writeFileSync(tmp, serializeSchedulerStore(records), { mode: 0o600 });
+    renameSync(tmp, path); // atomic over the target
+}
+/** A filesystem-backed {@link SchedulerStore} bound to a path (convenience for the daemon/backend constructors). */
+export function fileSchedulerStore(path) {
+    return {
+        load: () => loadSchedulerStore(path),
+        save: (records) => saveSchedulerStore(path, records),
+    };
+}
+/**
+ * The ONE cross-process mutation primitive for the shared scheduler store (board [1001]①/[1003]② —
+ * server L1-2 + shell 对抗评审 F1 双向合流后的契约层统一原语). Every WRITER (engine backend, resident
+ * daemon fire/reap, session reap, sweeps) must go through this instead of hand-rolled
+ * load→filter→save — the naked sequence is a lost-update race: two writers load the same base
+ * array, mutate independently, and the later `save` silently reverts the earlier one.
+ *
+ * Optimistic concurrency, format-preserving (no envelope/sidecar/lock file):
+ *   1. read the RAW file text and keep it as the base witness (missing file ⇒ empty witness);
+ *   2. run `fn(records)` — MUST be pure/replayable; return the next records array, or `null` to
+ *      abort with no write (e.g. "nothing to do" discovered under the latest base);
+ *   3. re-read the raw text just before committing — if it no longer equals the witness, a
+ *      concurrent writer landed: REPLAY from step 1 (bounded by `retries`, default 5);
+ *   4. commit via the same tmp+rename atomic write as {@link saveSchedulerStore}.
+ *
+ * Honest limits (declared in [1003], server ACK'd): the witness-check→rename window is not zero —
+ * this SHRINKS the race from "the whole read-modify-write span" to microseconds, it does not
+ * 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.
+ */
+export function mutateSchedulerStore(path, fn, opts) {
+    const maxRetries = Math.max(0, opts?.retries ?? 5);
+    const rawOf = () => {
+        try {
+            return readFileSync(path, 'utf-8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null; // missing file — parse side treats as []
+            throw e; // non-ENOENT (EACCES/EIO/EISDIR/…) must NOT collapse to "missing" — that would hand fn a fake
+            // empty baseline and the subsequent save() would overwrite real on-disk data with just fn's additions.
+        }
+    };
+    for (let attempt = 0;; attempt++) {
+        const baseRaw = rawOf();
+        const records = baseRaw === null ? [] : parseSchedulerStore(baseRaw);
+        const next = fn(records);
+        if (next === null)
+            return { ok: false, reason: 'aborted' };
+        if (rawOf() !== baseRaw) {
+            if (attempt >= maxRetries)
+                return { ok: false, reason: 'conflict_exhausted', retries: attempt };
+            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 };
+    }
+}
+/** [1057]① prompts contentDigest(node 绑定;browser-safe 纯层不带 crypto):
+ *  canonical JSON(stableStringify 同姿势:键序稳定+深度护栏)全量 sha256,**非盐化**
+ *  ([1050]② operator 对账位——center 产、server 透传、core manifest 归因三方可独立复算)。
+ *  入参=下发形的 {sections, scenarioOverrides?}(packId/contentDigest 自身不入 hash)。 */
+export function promptsContentDigest(payload) {
+    const canonical = stableStringify({
+        sections: payload.sections,
+        ...(payload.scenarioOverrides !== undefined ? { scenarioOverrides: payload.scenarioOverrides } : {}),
+    });
+    const hex = createHash('sha256').update(canonical, 'utf8').digest('hex');
+    const sectionHashes = Array.isArray(payload.sections)
+        ? payload.sections.map((s) => {
+            const t = s?.text;
+            return typeof t === 'string' ? sectionContentHash(t) : undefined;
+        })
+        : [];
+    return { contentDigest: `sha256:${hex}`, packId: `center:${hex.slice(0, 12)}`, sectionHashes };
+}
+/** 逐 section 对账锚(core 1.315 `PromptTextDeclaration.contentHash` 同刻度):sha256(text)。 */
+export function sectionContentHash(text) {
+    return `sha256:${createHash('sha256').update(text, 'utf8').digest('hex')}`;
+}

package/dist/scheduler-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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).
+ */
+/** A scheduled `when` — structurally identical to core `ScheduledIntent['when']`, inlined (contract stands alone). */
+export type SchedulerWhen = {
+    kind: 'cron';
+    expr: string;
+} | {
+    kind: 'at';
+    atMs: number;
+} | {
+    kind: 'delay';
+    delaySec: number;
+};
+/**
+ * A persisted scheduled record (durable across restarts). Required: id/scope/prompt/when/createdMs. Optional
+ * fields are additive — a future field is a non-breaking extension (readers preserve unknown fields on round-trip).
+ */
+export interface SchedulerRecord {
+    id: string;
+    scope: string;
+    /** 🔴 pinned from ctx (Runner-held), never the model; passed through to runTask unchanged. */
+    principal?: string;
+    sessionId?: string;
+    prompt: string;
+    when: SchedulerWhen;
+    label?: string;
+    createdMs: number;
+    nextRunMs?: number;
+}
+/**
+ * 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.
+ */
+export interface SchedulerStore {
+    load(): SchedulerRecord[];
+    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;
+/** One record dropped by {@link parseSchedulerStore} for failing {@link isSchedulerRecord} (malformed shape).
+ *  `index` = its position in the parsed array (for correlating with the source file); `record` = the raw
+ *  (unvalidated) value, for diagnostics. Additive — passing `onWarning` is optional. */
+export type SchedulerParseWarning = {
+    index: number;
+    kind: 'malformed-record';
+    record: unknown;
+};
+export declare function parseSchedulerStore(text: string, onWarning?: (w: SchedulerParseWarning) => void): SchedulerRecord[];
+/** 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;