Repository navigation
Commit d57be87
feat(spec): RestrictionProfileSchema, the closed shape of what a target environment does not let metadata do (#31191)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XYXcNDiasPwVizkPFMMxxVu)_
Refs #31156 (item 1)
Clause-②: yes (widening)
Metadata-protocol: added
Skills-docs: none — the profile is data a target environment publishes,
not a key an app author writes into a stack, and no reader ships in this
release; authors meet it through `os validate --target` (item 2 of the
card), whose refusals will name each rule.
## 维护者速读
- 改了什么:`@objectstack/spec/system` 新增 `RestrictionProfileSchema`(及
`RestrictionProfile`
类型),描述目标环境不允许元数据做什么:是否允许代码(钩子、函数、代码插件)、是否允许定时自动化、允许哪些内置流程节点类型、环境运行的 spec
与 skills 版本。
- 为什么改:cloud#3659 裁决 A,云端与本地只差一个限制档案;这是档案本身的契约,`os validate
--target`(本卡第 2 项)和云端发布接口(cloud 卡 3)都读它。
- 风险与回滚:纯新增的数据形状,无运行时读者、无门禁、无错误码,任何现有元数据不受影响。回滚即 revert。
-
先看:`packages/spec/src/system/restriction-profile.zod.ts`(四个必填维度,节点类型直接用
`FlowNodeAction`
枚举);`packages/spec/src/system/restriction-profile.test.ts`;`.changeset/31156-restriction-profile-schema.md`。
- 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run
src/system/restriction-profile.test.ts`,预期 `Tests 27 passed (27)`。
- 需要你做的:无,席位落地。
## What changes
`packages/spec/src/system/restriction-profile.zod.ts` (new), exported
from `@objectstack/spec/system`:
| Key | Shape | Meaning |
|:--|:--|:--|
| `allowCode` | `boolean`, required | metadata that carries code: object
lifecycle hooks, named handler functions, code plugins |
| `allowScheduledAutomation` | `boolean`, required | flows of `type:
'schedule'` and scheduled background `jobs` |
| `allowedFlowNodeTypes` | `FlowNodeAction[]`, required | the built-in
node types a flow may use; the element IS `FlowNodeAction` from
`automation/flow.zod.ts` (`FLOW_BUILTIN_NODE_TYPES` is the same list),
so there is no second list |
| `versions` | strict `{ spec, skills }`, required | the
`@objectstack/spec` and `@objectstack/skills` versions the environment
runs, each `SEMVER_2_0_0_VERSION_PATTERN` (reused from
`kernel/version-grammar.ts`) |
- Closed at both levels with `strictObject` (`.strict()` plus a named
surface and near-miss suggestions, e.g. `codeAllowed` → `allowCode`,
`specVersion` → `versions`).
- **An absent profile means no restriction.** The JSDoc states it: the
open default is holding no profile, not a profile with everything on.
Every dimension is required, so `{}` is refused rather than read as
"everything allowed", and an environment cannot publish a restriction it
did not spell out.
- Data only: no gate, no error code, no runtime enforcement. Item 2 (`os
validate --target`, `packages/cli`) and cloud card 3 are its readers.
- Where it lives: `src/system/`, beside `environment-artifact.zod.ts`,
the envelope a target environment serves to the runtime. The profile is
the same kind of thing (something an environment publishes about
itself), and `system/` is the domain for deployment and environment
shapes. `kernel/` holds the package manifest and plugin lifecycle, which
describe an app, not an environment.
- Regenerated: `api-surface`, `export-origins`, `declaration-map`,
`authorable-surface`, `json-schema.manifest`, the strictness-ledger
counts, and `content/docs/references/system/restriction-profile.mdx` (+
index rows). `packages/spec/llms.txt`: the system domain count 39 → 40
and the total 220 → 221 (`check:llms-txt` counts `*.zod.ts` modules).
- `type-alias-convention.pin.test.ts`: `RestrictionProfile` has no
default and no transform, so it is pinned isomorphic
(`Iso_system_restrictionProfile__RestrictionProfileSchema`, 841 → 842)
rather than given a `RestrictionProfileParsed` synonym.
## Why
objectstack-ai/cloud#3659, ruling A: one source of metadata-authoring
knowledge for every build channel, where a hosted environment differs
from local only by a restriction profile. The maintainer, verbatim:
「云端搭建唯一的区别是有一些限制,比如写代码是否允许,定时任务是否允许,流程允许使用到什程度」. This PR is the
profile's shape; item 2 and cloud card 3 build on it.
## Tests
`packages/spec/src/system/restriction-profile.test.ts`, 27 cases. Every
refusal asserts the issue `code` and `path` and that it is the only
issue:
- accepts a full profile, every built-in node type, and an empty node
list; the node element is `FlowNodeAction` by identity; published from
the system entry;
- absent profile: `.optional()` accepts `undefined`; `{}` is refused
with exactly the four `invalid_type` issues;
- requires each of the four keys and `versions.spec` /
`versions.skills`;
- refuses an unknown key on the profile (`unrecognized_keys`, and the
message names `allowCode`) and inside `versions`;
- refuses node types `approval`, `http_request`, `my_plugin_node`,
`Decision` (`invalid_value` at `allowedFlowNodeTypes[1]`);
- refuses versions `18`, `18.4`, `v18.4.0`, `^18.4.0`, `latest`,
`18.04.0` (`invalid_format`); refuses non-boolean flags.
**Ablations** (`scripts/ablation-replace.mjs`, each anchor hit once;
each leg restored to blob `fe21c2b8` = HEAD with `git diff HEAD` empty;
the test imports the schema from `src`, so no `dist/` is on the path):
| Leg | Mutation | Result |
|:--|:--|:--|
| node vocabulary | `.array(FlowNodeAction)` →
`.array(z.string().min(1))` | 5 failed / 22 passed (the identity case
and the four node refusals) |
| version grammar | the SemVer pattern import → `/ABL2\|./` | 6 failed /
21 passed (the six version refusals) |
| closed shape | top-level `strictObject(…)` →
`z.object(shape).passthrough()` | 1 failed / 26 passed (the unknown-key
refusal) |
| required | `allowCode` → `.optional()` | 2 failed / 25 passed
(`requires allowCode`, the `{}` case) |
## Acceptance notes
- Plugin-registered node types (`approval` / `approval_revise`, declared
as constants in `automation/approval.zod.ts` and executed by
`plugin-approvals`) are not `FlowNodeAction` ids, so a profile cannot
name them. That follows the ruling (the list is read from the spec's
node registry). How a reader treats a node type outside the built-in
registry is a question for item 2's reader, raised in the report.
- Every dimension is required, which is the stricter of the two readings
of "an absent profile means no restriction". The other reading (an
omitted dimension means unrestricted) is raised in the report as well.
## Verification
All on head `3a32985c` (base `8ef4d309`).
<details><summary>Gates: 104 derived, 104 run, all exit 0</summary>
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 104 families on this diff; each was
run with its exit code captured before any pipe, and `--ran` reconciles:
`104 derived famil(ies) accounted for — 104 run, 0 NOT-MEASURED`.
- First pass: 99 exit 0. Five re-run: `check:llms-txt` exit 1 was a real
stale count (fixed in `3a32985c`, then exit 0);
`check-plugin-teardown-shape.mjs --self-test` exit 3 (shallow clone;
after fetching `621a4876`, exit 0); `check:skill-examples`,
`check:dual-build-cjs-loads`, `check:lean-entry-closure` exit 3,
prerequisite only (after building the objectql and client-react
closures, exit 0).
- `pnpm --filter @objectstack/spec check:generated`: all 14 generated
artifacts up to date.
- `pnpm --filter @objectstack/spec typecheck`: exit 0
(`check:test-typecheck: OK`, 52 files / 240 errors held, unchanged).
- `eslint packages/spec --no-inline-config`: exit 0.
</details>
<details><summary>Tests</summary>
- `vitest run src/system/restriction-profile.test.ts`: 27 passed.
- Full `@objectstack/spec` suite under `os-verify-lock` (`VERDICT
command-exit 0`): Test Files 912 passed (912), Tests 27514 passed, 1
todo.
</details>
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5nzXgjDYseUz8kmybe)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 486b0a9 commit d57be87
16 files changed
Lines changed: 383 additions & 11 deletions
File tree
- .changeset
- content/docs/references
- system
- docs/audits/2026-07-unknown-key-strictness-ledger.counts
- packages/spec
- api-surface
- authorable-surface
- declaration-map
- export-origins
- json-schema.manifest
- src
- system
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| |||
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
35 | | - | |
| 35 | + | |
36 | 36 | | |
37 | | - | |
| 37 | + | |
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
| |||
329 | 329 | | |
330 | 330 | | |
331 | 331 | | |
332 | | - | |
| 332 | + | |
333 | 333 | | |
334 | 334 | | |
335 | 335 | | |
| |||
363 | 363 | | |
364 | 364 | | |
365 | 365 | | |
| 366 | + | |
366 | 367 | | |
367 | 368 | | |
368 | 369 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| |||
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
| 40 | + | |
40 | 41 | | |
41 | 42 | | |
42 | 43 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
44 | 44 | | |
45 | 45 | | |
46 | 46 | | |
| 47 | + | |
47 | 48 | | |
48 | 49 | | |
49 | 50 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | | - | |
| 22 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
598 | 598 | | |
599 | 599 | | |
600 | 600 | | |
| 601 | + | |
| 602 | + | |
601 | 603 | | |
602 | 604 | | |
603 | 605 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1000 | 1000 | | |
1001 | 1001 | | |
1002 | 1002 | | |
| 1003 | + | |
| 1004 | + | |
| 1005 | + | |
| 1006 | + | |
1003 | 1007 | | |
1004 | 1008 | | |
1005 | 1009 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
384 | 384 | | |
385 | 385 | | |
386 | 386 | | |
| 387 | + | |
| 388 | + | |
387 | 389 | | |
388 | 390 | | |
389 | 391 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
574 | 574 | | |
575 | 575 | | |
576 | 576 | | |
| 577 | + | |
| 578 | + | |
577 | 579 | | |
578 | 580 | | |
579 | 581 | | |
| |||
0 commit comments