Skip to content

Commit d57be87

Browse files
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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
feat(spec): `RestrictionProfileSchema` — the closed shape of what a target environment does not let metadata do, published by that environment
6+
7+
Clause-②: yes (widening)
8+
Metadata-protocol: added
9+
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`, whose refusals will name each rule.
10+
11+
`@objectstack/spec/system` exports `RestrictionProfileSchema` and its `RestrictionProfile` type. One source of metadata-authoring knowledge serves every build channel, and a hosted environment differs from a local one only by a restriction profile. This is that profile's shape:
12+
13+
- `allowCode` (boolean): whether metadata that carries code is allowed — object lifecycle hooks, named handler functions, code plugins.
14+
- `allowScheduledAutomation` (boolean): whether flows of `type: 'schedule'` and scheduled background jobs are allowed.
15+
- `allowedFlowNodeTypes`: the built-in flow node types a flow may use. Its items are `FlowNodeAction` ids, read from the spec's own node registry, so a type the registry does not name is refused and there is no second list to keep in step.
16+
- `versions: { spec, skills }`: the `@objectstack/spec` and `@objectstack/skills` versions the environment runs, each an exact SemVer 2.0.0 version.
17+
18+
The shape is strict at both levels and every key is required. **An absent profile means no restriction** (the local / open default): an environment with no restriction publishes no profile, and `{}` is refused rather than read as "everything allowed". The schema is data only: nothing in `@objectstack/spec` enforces it.

‎content/docs/references/index.mdx‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Protocol reference — every schema by module
33
navTitle: Protocol Reference
4-
description: Every schema published by @objectstack/spec — 1635 schemas across 14 protocol modules
4+
description: Every schema published by @objectstack/spec — 1636 schemas across 14 protocol modules
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -32,9 +32,9 @@ counts are sums of the rows they head. Regenerate with
3232
| [Security Protocol](/docs/references/security) | 6 | 37 | Permission sets, row-level security, sharing rules, tenancy posture. |
3333
| [Shared Protocol](/docs/references/shared) | 10 | 31 | Primitives used across every protocol — identifiers, HTTP, expressions, error maps, enums. |
3434
| [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
35-
| [System Protocol](/docs/references/system) | 39 | 295 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
35+
| [System Protocol](/docs/references/system) | 40 | 296 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
3636
| [UI Protocol](/docs/references/ui) | 16 | 175 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
37-
| **Total** | **212** | **1635** | 14 protocol modules |
37+
| **Total** | **213** | **1636** | 14 protocol modules |
3838

3939
---
4040

@@ -329,7 +329,7 @@ Studio designer metadata — the authoring surfaces for the protocols above.
329329

330330
## System Protocol
331331

332-
**Source:** `packages/spec/src/system/` · **Import:** `@objectstack/spec/system` · **39 pages, 295 schemas**
332+
**Source:** `packages/spec/src/system/` · **Import:** `@objectstack/spec/system` · **40 pages, 296 schemas**
333333

334334
The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance.
335335

@@ -363,6 +363,7 @@ The runtime environment — logging, jobs, cache, metrics, notifications, i18n a
363363
| [`push-config.zod.ts`](/docs/references/system/push-config) | `ApnsTransportConfig`, `FcmTransportConfig`, `PushDirectTransportConfig`, `PushRelayTransportConfig`, `PushServiceConfig`, `PushVendor` |
364364
| [`push-device.zod.ts`](/docs/references/system/push-device) | `UserDevice` |
365365
| [`registry-config.zod.ts`](/docs/references/system/registry-config) | `RegistryConfig`, `RegistrySyncPolicy`, `RegistryUpstream` |
366+
| [`restriction-profile.zod.ts`](/docs/references/system/restriction-profile) | `RestrictionProfile` |
366367
| [`search-engine.zod.ts`](/docs/references/system/search-engine) | `AnalyzerConfig`, `FacetConfig`, `SearchConfig`, `SearchIndexConfig`, `SearchProvider` |
367368
| [`security-context.zod.ts`](/docs/references/system/security-context) | `ComplianceAuditRequirement`, `ComplianceEncryptionRequirement`, `ComplianceFramework`, `DataClassification`, `DataClassificationPolicy`, `MaskingVisibilityRule`, `SecurityContextConfig`, `SecurityEventCorrelation` |
368369
| [`settings-client.zod.ts`](/docs/references/system/settings-client) | `SettingsChangeEvent` |

‎content/docs/references/system/index.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: System Protocol — complete schema reference
33
navTitle: System Protocol
4-
description: "The ObjectStack System Protocol in 39 reference pages: every schema in @objectstack/spec with its properties, types, defaults and a TypeScript example."
4+
description: "The ObjectStack System Protocol in 40 reference pages: every schema in @objectstack/spec with its properties, types, defaults and a TypeScript example."
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -37,6 +37,7 @@ This section contains all protocol schemas for the system layer of ObjectStack.
3737
<Card href="/docs/references/system/push-config" title="Push Config" description="Source: packages/spec/src/system/push-config.zod.ts" />
3838
<Card href="/docs/references/system/push-device" title="Push Device" description="Source: packages/spec/src/system/push-device.zod.ts" />
3939
<Card href="/docs/references/system/registry-config" title="Registry Config" description="Source: packages/spec/src/system/registry-config.zod.ts" />
40+
<Card href="/docs/references/system/restriction-profile" title="Restriction Profile" description="Source: packages/spec/src/system/restriction-profile.zod.ts" />
4041
<Card href="/docs/references/system/search-engine" title="Search Engine" description="Source: packages/spec/src/system/search-engine.zod.ts" />
4142
<Card href="/docs/references/system/security-context" title="Security Context" description="Source: packages/spec/src/system/security-context.zod.ts" />
4243
<Card href="/docs/references/system/settings-client" title="Settings Client" description="Source: packages/spec/src/system/settings-client.zod.ts" />

‎content/docs/references/system/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
"fate-supplement",
4545
"push-config",
4646
"push-device",
47+
"restriction-profile",
4748
"sms-config",
4849
"stack-server"
4950
]
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Restriction Profile — System Protocol
3+
navTitle: Restriction Profile
4+
description: "Restriction Profile schemas of the ObjectStack System Protocol: RestrictionProfile — each property with its type, default and a TypeScript example."
5+
---
6+
7+
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
8+
9+
<Callout type="info">
10+
**Source:** `packages/spec/src/system/restriction-profile.zod.ts`
11+
</Callout>
12+
13+
## TypeScript Usage
14+
15+
```typescript
16+
import { RestrictionProfileSchema } from '@objectstack/spec/system';
17+
import type { RestrictionProfile } from '@objectstack/spec/system';
18+
19+
// Validate data
20+
const result = RestrictionProfileSchema.parse(data);
21+
```
22+
23+
---
24+
25+
## RestrictionProfile
26+
27+
What a target environment does not let metadata do, published by that environment; an absent profile means no restriction
28+
29+
### Properties
30+
31+
| Property | Type | Required | Description |
32+
| :--- | :--- | :--- | :--- |
33+
| **allowCode** | `boolean` | ✅ | Whether metadata that carries code is allowed (object lifecycle hooks, named handler functions, code plugins) |
34+
| **allowScheduledAutomation** | `boolean` | ✅ | Whether scheduled automation is allowed (flows of type 'schedule' and scheduled background jobs) |
35+
| **allowedFlowNodeTypes** | `Enum<'start' \| 'end' \| 'decision' \| 'assignment' \| 'loop' \| 'create_record' \| 'update_record' \| 'delete_record' \| 'get_record' \| 'http' \| 'notify' \| 'save_notice' \| 'script' \| 'screen' \| 'wait' \| 'subflow' \| 'map' \| 'connector_action' \| 'parallel_gateway' \| 'join_gateway' \| 'boundary_event'>[]` | ✅ | Built-in flow node types a flow may use (FlowNodeAction ids); a built-in type not listed is forbidden |
36+
| **versions** | `{ spec: string; skills: string }` | ✅ | The @objectstack/spec and @objectstack/skills versions the environment runs |
37+
38+
### Nested Shape: `RestrictionProfile.versions`
39+
40+
| Property | Type | Required | Description |
41+
| :--- | :--- | :--- | :--- |
42+
| **spec** | `string` | ✅ | The @objectstack/spec version the environment runs (SemVer 2.0.0, e.g. 18.4.0) |
43+
| **skills** | `string` | ✅ | The @objectstack/skills version the environment runs (SemVer 2.0.0, e.g. 18.4.0) |
44+
45+
46+
---
47+

‎docs/audits/2026-07-unknown-key-strictness-ledger.counts/system.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ hand-patch a number here** — fix the code or the verdict and regenerate.
1919

2020
| Dir | Sites |
2121
|---|---|
22-
| `system/` | 395 |
22+
| `system/` | 397 |

‎packages/spec/api-surface/system.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -598,6 +598,8 @@
598598
"ResolvedSettingValue (type)",
599599
"ResolvedSettingValueSchema (const)",
600600
"ResolverDoc (interface)",
601+
"RestrictionProfile (type)",
602+
"RestrictionProfileSchema (const)",
601603
"ResultDialogLike (interface)",
602604
"RetryPolicy (type)",
603605
"RetryPolicyParsed (type)",

‎packages/spec/authorable-surface/system.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1000,6 +1000,10 @@
10001000
"system/ResolvedSettingValue:lockedReason",
10011001
"system/ResolvedSettingValue:source",
10021002
"system/ResolvedSettingValue:value",
1003+
"system/RestrictionProfile:allowCode",
1004+
"system/RestrictionProfile:allowScheduledAutomation",
1005+
"system/RestrictionProfile:allowedFlowNodeTypes",
1006+
"system/RestrictionProfile:versions",
10031007
"system/RetryPolicy:backoffMs",
10041008
"system/RetryPolicy:backoffMultiplier",
10051009
"system/RetryPolicy:jitter",

‎packages/spec/declaration-map/system.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,6 +384,8 @@
384384
"ResolvedGroupSchema": "system/ResolvedGroup",
385385
"ResolvedSettingValue": "system/ResolvedSettingValue",
386386
"ResolvedSettingValueSchema": "system/ResolvedSettingValue",
387+
"RestrictionProfile": "system/RestrictionProfile",
388+
"RestrictionProfileSchema": "system/RestrictionProfile",
387389
"RouteHandlerMetadata": "system/RouteHandlerMetadata",
388390
"RouteHandlerMetadataSchema": "system/RouteHandlerMetadata",
389391
"RowLevelIsolationStrategy": "system/RowLevelIsolationStrategy",

‎packages/spec/export-origins/system.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -574,6 +574,8 @@
574574
"ResolvedSettingValue": "src/system/settings-manifest.zod.ts#ResolvedSettingValue (type)",
575575
"ResolvedSettingValueSchema": "src/system/settings-manifest.zod.ts#ResolvedSettingValueSchema (const)",
576576
"ResolverDoc": "src/system/book.zod.ts#ResolverDoc (interface)",
577+
"RestrictionProfile": "src/system/restriction-profile.zod.ts#RestrictionProfile (type)",
578+
"RestrictionProfileSchema": "src/system/restriction-profile.zod.ts#RestrictionProfileSchema (const)",
577579
"ResultDialogLike": "src/system/i18n-resolver.ts#ResultDialogLike (interface)",
578580
"RetryPolicy": "src/shared/retry-policy.zod.ts#RetryPolicy (type)",
579581
"RetryPolicyParsed": "src/shared/retry-policy.zod.ts#RetryPolicyParsed (type)",

0 commit comments

Comments
 (0)