From 06dc8eb51ee4da76b30414c28948534e6d11c044 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 13:27:09 +0000 Subject: [PATCH] docs: scaffold examples pin exact; verify README names the scheduled-work switch The plugin package.json example in plugin-spec.mdx and the upgrading guide still showed the caret range the scaffolders wrote before PR #25539; they now show the exact pin. The verify README says that a local stack arms time-triggered flows only with OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true. Co-authored-by: Claude Claude-Session: https://claude.ai/code/session_01LKHDniRQSWjRJyDtacwpEd --- .../25442-verify-readme-scheduled-work.md | 12 ++++++++++++ content/docs/protocol/kernel/plugin-spec.mdx | 17 ++++++++++------- content/docs/upgrading.mdx | 5 +++-- packages/verify/README.md | 6 ++++++ 4 files changed, 31 insertions(+), 9 deletions(-) create mode 100644 .changeset/25442-verify-readme-scheduled-work.md diff --git a/.changeset/25442-verify-readme-scheduled-work.md b/.changeset/25442-verify-readme-scheduled-work.md new file mode 100644 index 00000000000..613aa2b33aa --- /dev/null +++ b/.changeset/25442-verify-readme-scheduled-work.md @@ -0,0 +1,12 @@ +--- +'@objectstack/verify': patch +--- + +docs(verify): the README says how a local stack arms scheduled flows + +Clause-②: no +Metadata-protocol: none + +The README's `flows.run(…, { system: true })` passage now says that this call works with scheduled work off. It also says that a local stack only arms time-triggered flows on their own cadence when `OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true` is set; package-authored scheduled work is off by default in every posture. + +What to do: nothing. Only the packaged README changes. diff --git a/content/docs/protocol/kernel/plugin-spec.mdx b/content/docs/protocol/kernel/plugin-spec.mdx index 49cee24e914..376673f84ca 100644 --- a/content/docs/protocol/kernel/plugin-spec.mdx +++ b/content/docs/protocol/kernel/plugin-spec.mdx @@ -716,11 +716,11 @@ Plugins are distributed as **NPM packages** for easy versioning and distribution ], "dependencies": { - "@objectstack/core": "^17.0.0" + "@objectstack/core": "18.0.0" }, "devDependencies": { - "@objectstack/cli": "^17.0.0", + "@objectstack/cli": "18.0.0", "typescript": "^5.3.0" }, @@ -739,12 +739,15 @@ Plugins are distributed as **NPM packages** for easy versioning and distribution The `typescript` floor above mirrors `SCAFFOLD_TYPESCRIPT_RANGE` in `packages/cli/src/commands/init.ts` — that constant, not this snippet, is the -authority the scaffolders emit from. The two `@objectstack/*` ranges have an +authority the scaffolders emit from. The two `@objectstack/*` versions have an authority in the same file: every `@objectstack/*` package in this monorepo is -published on one shared release version, and the scaffolders caret-pin each -dependency to the version of the CLI that generated the project -(`getCliVersion()`). A hand-written example cannot carry that live value, so it -carries the **current major's floor** — track it when the major moves. +published on one shared release version, and the scaffolders pin each +dependency **exactly** to the version of the CLI that generated the project +(`getCliVersion()`), never as a caret range. A patch on this line can break a +non-protocol surface, so a range would let the next install move you onto a +release you have not read. A hand-written example cannot carry that live value, +so it carries the **current major's first release**, pinned exactly — track it +when the major moves. ### Publishing to NPM diff --git a/content/docs/upgrading.mdx b/content/docs/upgrading.mdx index 5ddd731f924..1c8a8ec8618 100644 --- a/content/docs/upgrading.mdx +++ b/content/docs/upgrading.mdx @@ -78,8 +78,9 @@ command for this move; it is four steps you run yourself. *previous* release's author-time rules over your metadata. 2. **Regenerate the lockfile, and commit it** (`pnpm install` / `npm install` / `yarn install`). This is the step that actually moves the code. A project - pinned to exact versions moves because step 1 edited the pins; a project on the - scaffold's default ranges (`^17.0.0`) moves entirely here. Read whatever + pinned to exact versions (what the scaffolders write since 18.1.0) moves + because step 1 edited the pins; a project still on a caret range (`^18.0.0`, + what older scaffolds wrote) moves entirely here. Read whatever peer-dependency warnings this prints — the `--frozen-lockfile` install your CI runs skips resolution and will never print them. 3. **Check the two protocol declarations your app ships** — `specVersion` in diff --git a/packages/verify/README.md b/packages/verify/README.md index 560b8e221ac..e275965ac78 100644 --- a/packages/verify/README.md +++ b/packages/verify/README.md @@ -351,6 +351,12 @@ await stack.stop(); true })` starts a flow as the system principal through the `automation` service's own `execute`, the call the schedule trigger's tick makes, never through the trigger route, and hands back the engine's result unchanged. + That call does not wait for a schedule, so it works with scheduled work off. + For a local stack to arm time-triggered flows on their own cadence (rather + than list them as disabled by deployment policy), set + `OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true` in its environment: + package-authored scheduled work is off by default in every posture (see + Deployment › Environment variables in the docs). - A refusal from `flows.*` / `actions.run` is the route's ADR-0112 envelope (`VerifyRefusal`: `code`, `status`, `details`; `isVerifyRefusal(e)`); a refusal from `hooks.run` / `hooks.updateWhere` / `validate` / `rows` /