@zq-silk/yui 2.11.0 → 2.12.0

package/docs/schedules.md

@@ -1,6 +1,11 @@
 # Persistent time plans
 
-A Schedule answers **when** to admit a Run of an existing scoped Job. It owns
+For the installed Project maintenance plan and its user overrides, see
+[Built-in Project sync](project-sync.md) ([简体中文](project-sync.zh-CN.md)).
+
+A Schedule answers **when** to dispatch a scoped Job. It either admits a Run
+of an existing Job (default), or asks the Job layer to instantiate an exact
+definition revision as a new Job and admit its first Run. It owns
 the time rule and trigger progress, not the command, execution status or result.
 Immediate execution remains `job run`; manual Runs do not move a Schedule.
 All processing uses the existing Controller and the Job supervisor.
@@ -9,6 +14,7 @@ All processing uses the existing Controller and the Job supervisor.
 
 ```sh
 yui schedule create --global --schedule daily-probe --job probe \
+  --authorization service \
   --rule '{"kind":"cron","expression":"30 9 * * 1-5","timezone":"Asia/Shanghai"}'
 yui schedule list --global
 yui schedule show --global --schedule daily-probe
@@ -16,17 +22,26 @@ yui schedule disable --global --schedule daily-probe --revision 1
 yui schedule enable --global --schedule daily-probe --revision 2
 yui schedule update --global --schedule daily-probe --revision 3 \
   --rule '{"kind":"interval","anchor":"2026-10-17T00:00:00Z","everyMs":3600000}'
+# New Job per occurrence, pinned to the currently available source revision:
+yui schedule create --global --schedule isolated-probe --job probe \
+  --authorization service --target '{"kind":"new-job","definitionRevision":1}' \
+  --rule '{"kind":"interval","anchor":"2026-10-17T00:00:00Z","everyMs":3600000}'
+# Unlike disable, revoke also denies not-yet-started service Runs:
+yui schedule revoke --global --schedule isolated-probe --revision 1
 ```
 
 Create the referenced Job first using [the Job CLI](job-runs.md). Replace
-`--global` with `--task task-N` for a Task-owned Schedule. Global management
-requires a current authenticated Operator Session; Task callers cannot access
+`--global` with `--task task-N` for a Task-owned Schedule. Public local users can
+manage global plans without an Operator Session. Creating or rebinding a public
+plan requires the explicit `--authorization service` choice. Current Operator
+callers can also choose service authorization; omitting it on creation preserves
+the Session-bound behavior. Task callers cannot access
 global or other Tasks' plans. Assignment limits are checked against the Job
 on the server. A Project is a Job target, never an ownership scope.
 
 The Controller RPC is `schedule.control`. Its input is
-`{op,scope,caller,id?,jobId?,rule?,expectedRevision?}`. Supported `op` values
-are `create`, `list`, `show`, `update`, `enable`, `disable`. `scope` uses the
+`{op,scope,caller,id?,jobId?,target?,authorization?,rule?,expectedRevision?}`. Supported `op` values
+are `create`, `list`, `show`, `update`, `enable`, `disable`, `revoke`. `scope` uses the
 Job `JobScope` contract. Trusted ingress must resolve/authenticate `caller`;
 client-supplied scope/identity is not authorization. `create` requires `id`,
 `jobId`, `rule`; all edits require the observed `expectedRevision`. `update`
@@ -35,9 +50,17 @@ revalidating both old visibility and new execution authority. Scope is immutable
 Rule updates retain enabled status only for an already enabled plan; all other
 states become disabled with the new future rule and require explicit enable.
 
+`target` defaults to `{"kind":"existing-job"}`. `{"kind":"new-job",
+"definitionRevision":N}` requires the exact currently available source version.
+A source edit never silently changes that pinned selection; explicitly update
+the target and, for service plans, reauthorize. Job owns deterministic instance
+identity and `instantiation` provenance (`sourceId`, `sourceRevision`, occurrence
+`key`). It does not create a Task. Each new instance has its own overlap scope;
+existing-job mode retains one Job's overlap behavior.
+
 Create/edits return the Schedule; list returns visible Schedule records.
-Show returns `{schedule,lastSuccess}`. `lastSuccess` is the latest readable
-**succeeded JobRun** triggered by this Schedule under its current Job, or null.
+Show returns `{schedule,lastSuccess,runs}`. `lastSuccess` is the latest readable
+**succeeded JobRun** triggered by this Schedule across its historical Jobs, or null.
 It is derived from Run history, never a separately writable Schedule field.
 Retargeting does not move or erase the old Job's Run history.
 
@@ -71,7 +94,7 @@ prevents clock rollback or rule edits from replaying old progress.
 Rule updates increase `generation`; enable retains it. The internal trigger
 key is `<schedule-id>:<generation>:<UTC-due>`, scoped to the Job.
 
-Admission and advancement commit in the same Store transaction. Repeated scans
+Instance creation, first Run admission and advancement commit in the same Store transaction. Repeated scans
 and Controller replacement retain the same Run and occurrence identity.
 The transaction never spawns. The supervisor starts committed Runs and
 preserves its existing unknown-effect and exact-process safeguards.
@@ -86,13 +109,15 @@ Task terminal shutdown. Disabling does not cancel an already admitted Run,
 and cancelling a Run does not disable its Schedule.
 
 `lastAttempt` records `at`, `dueAt`, `outcome` (`admitted`, `overlap`, `blocked`),
-optional exact `runId`, and reason. An overlap Run is the occupying execution,
+optional exact `jobId`/`runId`, `generation`, and reason. Old receipts retain
+only what was originally known; migration does not invent those references.
+An overlap Run is the occupying execution,
 not a successful execution of this occurrence. Recurring overlap skips that
 coalesced tick and advances; once overlap retains its original due instant and
 retries admission on a later pass without adding a queued Run.
 Failed Runs stay in Job history; the next recurring tick follows the same plan.
 
-Creation, update and enable capture the authenticated Session binding and Job
+Session-authorized creation, update and enable capture the authenticated Session binding and Job
 revision. They do not grant execution to a replacement Session or a changed
 Job definition. Before each admission both are checked again, along with current
 Job/Task/workspace prerequisites. Revocation or a changed definition stops the
@@ -100,8 +125,31 @@ plan as `needs-attention`; an authorized current manager must inspect and
 explicitly enable it. Controller restart alone does not revoke the binding.
 Worker-owned plans also retain the current Assignment boundary.
 
+Service authority is a separate explicit grant stored on the Schedule. The
+compiled internal `schedule` registration permits only global `system.noop`
+and `project.refresh`; it does not permit Task shell execution, arbitrary code,
+or additional scopes. `origin=builtin`, `caller.scope=service` and client-supplied
+grant fields cannot create a service identity. Management first authenticates
+the ordinary public/managed caller and checks the actual Job target.
+The grant binds Home, Schedule, dispatch mode, exact definition, action, Project
+and input. Admission and runner start recheck current validity; Project refresh
+also rechecks after waiting for its maintenance lock. Replacing Operator Sessions
+does not revoke a service grant. Source/configuration changes block the plan
+with retained reasons; no silent rebind occurs.
+Service Run results remain in Job history and do not enqueue an Operator wake.
+Dispatch errors still use the existing attention notification when a recipient exists.
+
+`disable` only stops future dispatch; it does not invalidate the grant of an
+already admitted Run. `revoke` disables the plan and invalidates the grant,
+preventing queued service Runs from starting (not cancelling effects already
+in flight). An explicit `enable --authorization service` grants a fresh identity;
+it never resurrects old revoked Runs. Ordinary enable/rule edits retain an
+unchanged active grant. Reauthorization and source/target changes are deliberate
+management operations, not automatic repairs.
+
 Unclassified admission failures roll back, stop that plan, persist the reason
-and notify its Task Leader or global Operator via existing durable inboxes.
+and notify its Task Leader or configured global Operator via existing durable inboxes.
+If no Operator role exists, the plan/reason remains inspectable without creating one.
 No new recovery queue, lease or automatic retry protocol is introduced.
 
 Task stop marks enabled plans as needing attention; restarting execution alone
@@ -114,14 +162,20 @@ settlement guards. A reopened Task does not implicitly resume retired plans.
 
 ## Storage and downstream integration
 
-Storage **1.9 → 1.10** appends `schedules`, keyed by `(scope_key,schedule_id)`,
-and its due index. Old Job/Run bytes and published baseline checksums remain
-unchanged. New Homes initialize 1.10; existing Homes require the centralized
+Storage **1.15 → 1.16** adds explicit target and authorization kinds to existing
+plans, preserving Session bindings, identities, rules, progress and old receipts.
+Original Schedule bytes are archived under migration 16. It never turns historical
+Session authority into a service grant. New optional Job instance provenance and
+Run service-grant references use the existing tables. The published **1.9 → 1.10**
+DDL and all older transitions remain unchanged. New Homes initialize 1.16;
+existing Homes require the centralized
 explicit upgrade path. No real Home migration or package release is implied.
 
 `src/schedule/schedule.ts` exports `Schedule`, `ScheduleRule`, time calculation
 and validation. `src/controller/scheduleControl.ts` owns management and bounded
-reconciliation; `admitJobRun` remains the only execution admission seam.
+reconciliation; Job's `instantiateJobRun` composes instance creation with
+`admitJobRun`, the execution admission seam. No ScheduleRun state or second
+writable execution result is introduced.
 Consumers should use RPC/service responses rather than write storage directly.
 
 Project refresh is a separate controlled Job action supplied by Task128.

package/docs/storage-baseline.md

@@ -2,7 +2,44 @@
 
 # Storage baseline 1.0
 
-Current storage is 1.14. The 1.13 → 1.14 transition removes the Role foreign key
+Current storage is 1.20. The 1.19 → 1.20 transition adds Agent Job configurations,
+optional Job ownership on Global Roles, and the `agent_job_runs` table for
+exact original-message/native-attempt evidence and explicit business results.
+Existing Role, Session, process Run and artifact identities are unchanged;
+no Agent or native Session is invented during migration.
+
+The 1.18 → 1.19 transition adds optional immutable Task
+creation source, exact Run delegation and Task/WorkItem result-reference kinds.
+Existing valid payload bytes, ordinary source-less Tasks, unknown effects and
+fixed references are unchanged; no historical source or authority is inferred.
+SQL layout is unchanged.
+
+The additive 1.17 → 1.18 transition admits builtin
+Project-sync provenance, a compiled service issuer and a separate user-enabled
+preference on new Schedules. SQL layout and every existing payload remain unchanged;
+it neither adopts custom Jobs nor fabricates historical grants or Runs.
+Installation is a Controller operation, separate from storage migration.
+
+The 1.16 → 1.17 transition adds optional append-only
+JobRun artifact references and scope/Run-isolated local Git repositories.
+Existing payload bytes and Task Git repositories/frozen references remain
+unchanged; no historical artifact, provenance or authorization is inferred.
+No SQL layout change or automatic cleanup is introduced.
+
+The 1.15 → 1.16 transition adds explicit Schedule
+dispatch targets and authorization kinds. Existing plans keep their exact Session
+authority, rules, identity and progress; original bytes are archived under migration
+16. No service permission is inferred. New service grants and Job instance
+provenance use the same tables; no ScheduleRun lifecycle is introduced.
+
+The 1.14 → 1.15 transition adds separate Job business
+results derived from saved process results, archiving original Run payload bytes
+under migration 15. It does not infer structured business data from logs, change
+execution identities, replay effects or rewrite frozen Context/Integration evidence.
+SQL layout is unchanged. Public immediate builtin admissions use an explicit
+Home/Run-bound user authority, not an invented Session or Schedule authorization.
+
+The 1.13 → 1.14 transition removes the Role foreign key
 from `global_role_session_sets`, preserving every payload byte and rebuilding
 its retry index. Stopped Session identity/history can then outlive Role removal
 without granting authority. No new authorization table or inferred history is

package/docs/storage-baseline.zh-CN.md

@@ -2,7 +2,33 @@
 
 # 存储基线 1.0
 
-当前存储为 1.14。1.13 → 1.14 只移除 `global_role_session_sets` 对 Role 的外键，
+当前存储为 1.20。1.19 → 1.20 增加 Agent Job 配置、Global Role 的可选 Job
+归属和 `agent_job_runs` 表，保存原始消息、准确原生尝试与显式业务结果。
+保留现有 Role、Session、进程 Run 和固定产物身份；迁移不创建 Agent 或原生会话。
+
+1.18 → 1.19 增加 Task 可选且不可改写的创建来源、准确 Run
+委托及 Task/WorkItem 结果引用，不改变 SQL 布局或旧 payload 字节。
+普通历史 Task 仍无来源，不补造权限、来源或结果；未知效果与固定产物引用保持。
+
+1.17 → 1.18 允许新记录携带内置 Project 同步来源、
+编译期注册服务签发者及独立的用户启停偏好；SQL 布局和已有 payload 原字节不变。
+迁移不接管手建 Job、不补造历史授权或 Run；安装由 Controller 单独核对。
+
+1.16 → 1.17 增加 JobRun 可选的只追加产物引用，
+以及按 scope 和 Run 隔离的本地 Git 正式产物库。原 payload 字节、
+Task 产物库及冻结引用保持不变，不补造历史产物、来源或授权，
+不改变 SQL 布局，也不增加自动清理。
+
+1.15 → 1.16 增加明确的 Schedule 派发目标及授权类型；
+原计划保留准确 Session 授权、规则、身份与进度，原始字节归档于 migration 16。
+不推导或升级为服务权限。新增服务授权和 Job 实例来源沿用原表，不新增 ScheduleRun 生命周期。
+
+1.14 → 1.15 根据已保存的进程结果增加独立的 Job 业务结果，
+原始 Run payload 字节归档于 migration 15；不从日志猜测结构化业务数据，
+不改执行身份，不重放动作，也不改冻结 Context 或 Integration 证据。SQL 布局不变。
+公共即时 builtin 使用绑定 Home/Run 的 user 授权，不伪造 Session，也不授予 Schedule 持久权限。
+
+1.13 → 1.14 只移除 `global_role_session_sets` 对 Role 的外键，
 原样保留 payload 并重建 retry 索引，使已停止会话的身份／历史在角色移除后继续保留，
 但不赋予权限。不新增授权表，不补造已经丢失的历史。普通读取要求当前存储版本，
 已有 Home 只能通过显式受支持升级迁移，不能在读取时自动迁移。

package/docs/testing/verification-levels.md

@@ -50,12 +50,12 @@ is required.
 ## Permanent core smoke
 
 `npm test` and `npm run test:core` build the checkout and run the maintained suite.
-The stable suite owns current storage 1.14 and its declared 1.0 through 1.13 minor
+The stable suite owns current storage 1.20 and its declared 1.0 through 1.19 minor
 transition. It contains no undeclared historical format compatibility path.
 
 Current coverage includes:
 
-1. Fresh storage 1.14, exact schema/record validation, no initialization over
+1. Fresh storage 1.20, exact schema/record validation, no initialization over
    unknown data, and rejection of old integer formats without mutation.
 2. Exact-version staging, mismatched-target refusal, same-major contiguous
    minor preflight, explicit maintenance-owner identity across handover, and

package/docs/testing/verification-levels.zh-CN.md

@@ -36,12 +36,12 @@ Yui 是一个单用户本地产品。永久验证保护关键的 happy path 和
 ## 永久 core smoke
 
 `npm test` 和 `npm run test:core` 构建当前 checkout 并运行维护中的套件。
-稳定套件维护当前存储 1.14 和明确声明的 1.0 至 1.13 连续小版本迁移，
+稳定套件维护当前存储 1.20 和明确声明的 1.0 至 1.19 连续小版本迁移，
 不包含未声明的历史格式兼容路径。
 
 当前覆盖包括：
 
-1. 新建存储 1.14、精确结构与记录校验、禁止覆盖未知数据库、无修改拒绝旧整数格式。
+1. 新建存储 1.20、精确结构与记录校验、禁止覆盖未知数据库、无修改拒绝旧整数格式。
 2. 精确版本暂存、目标不匹配拒绝、同主版本连续小版本预检、交接锁显式所有者，
    以及恢复时核对捕获的协议和存储身份，不接受缺失字段。
 3. 持久 Task／Message／Decision 上下文、Draft 激活权威、mailbox 认领、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,