@astrale-os/sdk 0.6.0-beta.55 → 0.6.0-beta.57
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -10
- package/dist/application/index.d.ts +2 -1
- package/dist/application/query/execution/crossings.d.ts +6 -1
- package/dist/application/query/execution/crossings.js +15 -1
- package/dist/application/query/execution/legacy/declared-classes.d.ts +10 -0
- package/dist/application/query/execution/legacy/declared-classes.js +9 -0
- package/dist/application/requirements/canonical.d.ts +7 -0
- package/dist/application/requirements/canonical.js +16 -0
- package/dist/application/requirements/classes.d.ts +9 -7
- package/dist/application/requirements/classes.js +35 -42
- package/dist/application/requirements/functions.d.ts +3 -1
- package/dist/application/requirements/functions.js +12 -27
- package/dist/application/requirements/index.d.ts +34 -16
- package/dist/application/requirements/index.js +17 -20
- package/dist/application/requirements/legacy/authority.d.ts +21 -0
- package/dist/application/requirements/{authority.js → legacy/authority.js} +5 -2
- package/dist/application/requirements/legacy/classes.d.ts +22 -0
- package/dist/application/requirements/legacy/classes.js +24 -0
- package/dist/application/requirements/legacy/core.d.ts +30 -0
- package/dist/application/requirements/{core.js → legacy/core.js} +15 -13
- package/dist/application/requirements/legacy/functions.d.ts +7 -0
- package/dist/application/requirements/legacy/functions.js +15 -0
- package/dist/application/requirements/legacy/index.d.ts +43 -0
- package/dist/application/requirements/legacy/index.js +1 -0
- package/dist/application/requirements/legacy/requirements.d.ts +31 -0
- package/dist/application/requirements/legacy/requirements.js +31 -0
- package/dist/application/requirements/requirement.d.ts +30 -19
- package/dist/application/requirements/roles.d.ts +17 -0
- package/dist/application/requirements/roles.js +62 -0
- package/dist/application/requirements/scopes.d.ts +16 -0
- package/dist/application/requirements/scopes.js +34 -0
- package/dist/deployment/build/build.d.ts +3 -5
- package/dist/deployment/build/compile.js +12 -64
- package/dist/deployment/build/legacy/requirements.d.ts +11 -0
- package/dist/deployment/build/legacy/requirements.js +79 -0
- package/dist/deployment/build/material.js +0 -3
- package/dist/execution/invocation/dispatch/context.js +2 -1
- package/dist/platform/schema/class-authoring.d.ts +9 -7
- package/dist/platform/schema/class-authoring.js +3 -2
- package/dist/platform/schema/index.d.ts +1 -1
- package/dist/testing/query.js +2 -1
- package/dist/tooling/linter/adapters/typescript/discover.js +8 -2
- package/dist/tooling/linter/adapters/typescript/index.d.ts +6 -0
- package/dist/tooling/linter/adapters/typescript/index.js +1 -0
- package/dist/tooling/linter/adapters/typescript/legacy.d.ts +20 -0
- package/dist/tooling/linter/adapters/typescript/legacy.js +28 -0
- package/dist/tooling/linter/implementations/source/callable-requirements.d.ts +1 -2
- package/dist/tooling/linter/implementations/source/callable-requirements.js +7 -44
- package/dist/tooling/linter/implementations/source/const-initializer.d.ts +3 -0
- package/dist/tooling/linter/implementations/source/const-initializer.js +31 -0
- package/dist/tooling/linter/implementations/source/domain-requirements.d.ts +8 -0
- package/dist/tooling/linter/implementations/source/domain-requirements.js +35 -0
- package/dist/tooling/linter/implementations/source/global.js +21 -8
- package/dist/tooling/linter/implementations/source/legacy/requirements.d.ts +10 -0
- package/dist/tooling/linter/implementations/source/legacy/requirements.js +40 -0
- package/dist/tooling/linter/implementations/source/legacy-folders.d.ts +3 -0
- package/dist/tooling/linter/implementations/source/legacy-folders.js +126 -0
- package/dist/tooling/linter/implementations/source/mutations.js +7 -22
- package/dist/tooling/linter/implementations/source/requirement-entries.d.ts +24 -0
- package/dist/tooling/linter/implementations/source/requirement-entries.js +52 -0
- package/dist/tooling/linter/implementations/source/schema.d.ts +3 -0
- package/dist/tooling/linter/implementations/source/schema.js +9 -5
- package/dist/tooling/linter/implementations/source/tests.js +1 -1
- package/dist/tooling/linter/implementations/source/verifiers.js +2 -0
- package/dist/tooling/linter/policy/generated.js +2 -2
- package/dist/tooling/linter/requirements/registry.js +2 -0
- package/docs/accounts/scenarios.tsv +12 -0
- package/docs/handler-dependencies.md +5 -3
- package/docs/legacy.md +113 -0
- package/docs/queries.md +3 -2
- package/docs/requirements.md +134 -0
- package/package.json +4 -4
- package/dist/application/requirements/authority.d.ts +0 -7
- package/dist/application/requirements/core.d.ts +0 -14
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Requirements: Kernel Roles and scopes
|
|
2
|
+
|
|
3
|
+
A Domain's release says what it needs from the instance that installs it: the Kernel Roles it
|
|
4
|
+
binds, and the scopes the installed Domain holds. `requirements` from `@astrale-os/sdk/domain`
|
|
5
|
+
captures them; Build compiles them to the release's `requirements.capabilities`, which the Kernel
|
|
6
|
+
admits and validates against the exact dependency closure before anything is installed.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { defineDomain, requirements } from '@astrale-os/sdk/domain'
|
|
10
|
+
import { K, schema as language } from '@astrale-os/sdk/schema'
|
|
11
|
+
|
|
12
|
+
import runtime from './runtime.js'
|
|
13
|
+
import { ShellSchema } from './schema/index.js'
|
|
14
|
+
|
|
15
|
+
const S = language.resolve(ShellSchema)
|
|
16
|
+
const guest = S.core.nodes['profile.guest']
|
|
17
|
+
const member = S.core.nodes['profile.member']
|
|
18
|
+
const admin = S.core.nodes['profile.admin']
|
|
19
|
+
|
|
20
|
+
export const domain = defineDomain({
|
|
21
|
+
schema: ShellSchema,
|
|
22
|
+
runtime,
|
|
23
|
+
requirements: requirements({
|
|
24
|
+
roles: [
|
|
25
|
+
// Kernel Roles: the Domain's profiles extend them, its admin profile grants them.
|
|
26
|
+
{ role: K.core.nodes.reader, members: [guest], granters: [admin] },
|
|
27
|
+
{ role: K.core.nodes.writer, members: [member], granters: [admin] },
|
|
28
|
+
// The installed Domain itself reads authority, to read the compositions it judges.
|
|
29
|
+
{ role: K.core.nodes['authority.reader'], members: [requirements.domain] },
|
|
30
|
+
// The Domain's own Roles: a profile bundles another, the admin profile grants them.
|
|
31
|
+
{ role: guest, members: [member], granters: [admin] },
|
|
32
|
+
{ role: member, members: [admin], granters: [admin] },
|
|
33
|
+
{ role: admin, granters: [admin] },
|
|
34
|
+
],
|
|
35
|
+
scopes: [
|
|
36
|
+
{ on: K.classes.Domain, operations: ['read'] },
|
|
37
|
+
{ on: S.classes.User.static.methods.provision, operations: ['call'] },
|
|
38
|
+
],
|
|
39
|
+
}),
|
|
40
|
+
})
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Roles
|
|
44
|
+
|
|
45
|
+
A Role binding is `{ role, members?, granters? }` and names members, granters, or both.
|
|
46
|
+
|
|
47
|
+
- `role` is a Core Node whose Class is a Role (`K.classes.Role` or a Class extending it): one of
|
|
48
|
+
the Domain's own, such as `S.core.nodes['profile.admin']`, or one of a dependency, such as
|
|
49
|
+
`K.core.nodes.reader`.
|
|
50
|
+
- Each **member** extends the Role: the installation writes `member -[extends_with]-> role`, so a
|
|
51
|
+
holder of the member holds the Role.
|
|
52
|
+
- Each **granter** may grant and revoke the Role: the installation writes `can_grant_extension`
|
|
53
|
+
and `can_revoke_extension` from the granter toward the Role. Only an installation writes them.
|
|
54
|
+
- A holder is `requirements.domain` (the installed Domain, `{ kind: 'domain' }`), one of the
|
|
55
|
+
Domain's own Core Identities, or a Core Identity of a dependency, by its resolved definition. A
|
|
56
|
+
Core Identity of a dependency (Kernel law K1, such as the Shell's `profile.admin` granting a
|
|
57
|
+
product Domain's Roles) may hold only the Domain's own Roles, so no two installations declare
|
|
58
|
+
the same Edge. Build refuses it on a dependency's Role with `A Core Identity of a dependency
|
|
59
|
+
holds only the Domain's own Roles.`
|
|
60
|
+
|
|
61
|
+
A release binding is the only way a Domain composes Identities into Roles, its own included: the
|
|
62
|
+
Kernel DSL refuses a Core Edge whose Class is not the Domain's own (`DV_CORE_EDGE_CLASS`), and
|
|
63
|
+
Kernel `extends_with` is final. Bundles such as `member` extending `guest`, or a Team extending a
|
|
64
|
+
Role, are therefore `{ role: guest, members: [member] }` here, never `core.edge(…)`. The Kernel
|
|
65
|
+
projects each binding as the same `extends_with`, ungated when the Domain owns the Role.
|
|
66
|
+
|
|
67
|
+
## Scopes
|
|
68
|
+
|
|
69
|
+
A scope is `{ on, operations }`. On a Class (a resolved Class or its `ClassRef`) it holds Class
|
|
70
|
+
operations among `create`, `read`, `traverse`, `update` and `delete`; on a Function or Method (by
|
|
71
|
+
its resolved definition) it holds `['call']`. The installed Domain holds each scope it names.
|
|
72
|
+
|
|
73
|
+
A scope bounds what the Domain does for a caller: when a handler acts for its caller, the Kernel
|
|
74
|
+
admits the operation only within the Domain's scopes, and the target's Policy still decides for the
|
|
75
|
+
caller. A Domain acting as itself is decided by the target's Policy alone, so a protected Kernel
|
|
76
|
+
callable needs the Domain to hold its Kernel Role: `query` admits a holder of `graph.reader`,
|
|
77
|
+
`mutate` of `graph.writer`, `register` of `identity.registrar`, `install` of `domain.installer`.
|
|
78
|
+
That Role also bounds the Domain's calls for a caller, since the Kernel admits a delegated call when
|
|
79
|
+
the Domain itself passes the callable's Policy, so a `call` scope on a Kernel callable adds nothing
|
|
80
|
+
to it. A scope toward a Kernel target installs only under Root (A20), which is why
|
|
81
|
+
`create-astrale-domain` declares the two graph Roles and no scope.
|
|
82
|
+
|
|
83
|
+
Before a Query sends anything, the SDK checks that each relation crossing a Class of a dependency
|
|
84
|
+
other than the Kernel is covered by the scopes `read` and `traverse` on that Class or a parent
|
|
85
|
+
(S12, see [Queries](queries.md)). The `astrale-domain` lint rules read a `call` scope as the exact
|
|
86
|
+
requirement of a remote invocation (`PRV-XDOM-REQ`, `FNC-XDOM-REQ`, `DOM-CALL-DECLARED`) and Class
|
|
87
|
+
scopes as the authority of a foreign Mutation plan (`MUT-PLAN-REQ`).
|
|
88
|
+
|
|
89
|
+
## Capture and Build
|
|
90
|
+
|
|
91
|
+
`requirements(input)` returns a frozen, canonical value that `defineDomain` admits:
|
|
92
|
+
|
|
93
|
+
- Roles sorted by the Key of their Role; holders sorted by Key with `requirements.domain` first;
|
|
94
|
+
scopes sorted by the Key of their target; Class operations in the order above.
|
|
95
|
+
- A duplicate Role, holder, scope or operation, an empty `members`, `granters` or `operations`, a
|
|
96
|
+
binding without members or granters, a target of the wrong kind, or an unknown key throws a
|
|
97
|
+
`TypeError`. `requirements()` and empty lists capture nothing.
|
|
98
|
+
|
|
99
|
+
Build passes the value to the published Kernel's `admitRequirements` and `validateRequirements`:
|
|
100
|
+
a Role must be a Core Node whose Class satisfies `K.classes.Role`, a holder the Domain or one of its
|
|
101
|
+
own Core Identities, and a scope target a Class or an executable callable of the Domain or of its
|
|
102
|
+
exact dependency closure. Empty requirements compile to `{ capabilities: {} }`, the same bytes as a
|
|
103
|
+
Domain with no requirements.
|
|
104
|
+
|
|
105
|
+
## From the legacy shape
|
|
106
|
+
|
|
107
|
+
Releases published before Kernel Roles declare `functions`, `classes`, `authority` and `core`.
|
|
108
|
+
`requirements` still captures that shape and Build compiles it to the same bytes as before; it is
|
|
109
|
+
deprecated (L-SDK-1, see [the legacy method](legacy.md)). A requirement set carries one shape,
|
|
110
|
+
never both: `requirements({ roles, functions })` throws. Moving a Domain:
|
|
111
|
+
|
|
112
|
+
| Legacy | Roles and scopes |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| `functions: [f]` | `scopes: [{ on: f, operations: ['call'] }]`; for a protected Kernel callable the Domain calls as itself, also `{ role: K.core.nodes['graph.reader'], members: [requirements.domain] }` (its Kernel Role) |
|
|
115
|
+
| `classes: [{ class: C, operations }]` | `scopes: [{ on: C, operations }]` |
|
|
116
|
+
| `core: [{ subject: s, ... }]` | a Role with the capabilities, and `{ role, members: [s] }` |
|
|
117
|
+
| `authority: { grant, revoke }` | `granters` of the Roles the Domain may grant |
|
|
118
|
+
|
|
119
|
+
Switching a release from the legacy shape to Roles and scopes replaces every capability the
|
|
120
|
+
installation posed for the previous release: declare every Role and scope the Domain still uses.
|
|
121
|
+
|
|
122
|
+
## Design record
|
|
123
|
+
|
|
124
|
+
- **Decision.** The SDK authors the Kernel's Role and scope requirements as its target API, for
|
|
125
|
+
the accounts, groups and Roles design without inheritance (Shell, 2026-10-30): a Domain's
|
|
126
|
+
release binds Roles to holders and holds scopes; it no longer authors capabilities by Operation.
|
|
127
|
+
- **Amendments.** Build no longer refuses Roles and scopes: a build carries them or the legacy
|
|
128
|
+
shape, never both. The Query crossing check S12 and the source rules `PRV-XDOM-REQ`,
|
|
129
|
+
`FNC-XDOM-REQ`, `DOM-CALL-DECLARED` and `MUT-PLAN-REQ` read scopes; their wording in
|
|
130
|
+
`knowledge/` names them. The `create-astrale-domain` scaffold declares its graph Roles and scopes.
|
|
131
|
+
- **Delivery.** Step 1 of the design's delivery: this SDK release precedes the Shell minor that
|
|
132
|
+
declares its profiles as Roles. K1 holders are admitted since `@astrale-os/kernel-protocol`
|
|
133
|
+
1.0.0-beta.35.
|
|
134
|
+
Scenario evidence: [accounts/scenarios.tsv](accounts/scenarios.tsv).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astrale-os/sdk",
|
|
3
|
-
"version": "0.6.0-beta.
|
|
3
|
+
"version": "0.6.0-beta.57",
|
|
4
4
|
"description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"astrale",
|
|
@@ -266,7 +266,7 @@
|
|
|
266
266
|
"@lucide/icons": "1.34.0",
|
|
267
267
|
"@typescript/native-preview": "7.0.0-dev.20260707.2",
|
|
268
268
|
"cross-spawn": "7.0.6",
|
|
269
|
-
"hono": "^4.13.
|
|
269
|
+
"hono": "^4.13.11",
|
|
270
270
|
"jose": "^6.2.9",
|
|
271
271
|
"semver": "7.8.5",
|
|
272
272
|
"typescript": "~6.0.3"
|
|
@@ -278,7 +278,7 @@
|
|
|
278
278
|
"@cloudflare/workers-types": "^5.20261023.1",
|
|
279
279
|
"@commitlint/cli": "~21.2.2",
|
|
280
280
|
"@commitlint/config-conventional": "~21.2.2",
|
|
281
|
-
"@hono/node-server": "^2.1.
|
|
281
|
+
"@hono/node-server": "^2.1.3",
|
|
282
282
|
"@hono/node-server-v1": "npm:@hono/node-server@1.19.10",
|
|
283
283
|
"@restatedev/restate-sdk": "1.17.0",
|
|
284
284
|
"@restatedev/restate-sdk-cloudflare-workers": "1.17.0",
|
|
@@ -294,7 +294,7 @@
|
|
|
294
294
|
"preact": "^10.29.8",
|
|
295
295
|
"tsx": "^4.23.12",
|
|
296
296
|
"vite": "^8.2.4",
|
|
297
|
-
"vitest": "^5.0.
|
|
297
|
+
"vitest": "^5.0.5",
|
|
298
298
|
"yaml": "^2.9.0",
|
|
299
299
|
"zod": "4.6.7"
|
|
300
300
|
},
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
import type { AuthorityOperation } from '../../platform/schema/index.js';
|
|
2
|
-
import type { AuthorityRequirements } from './requirement.js';
|
|
3
|
-
export interface AuthorityRequirementsInput {
|
|
4
|
-
readonly grant?: readonly [AuthorityOperation, ...AuthorityOperation[]];
|
|
5
|
-
readonly revoke?: readonly [AuthorityOperation, ...AuthorityOperation[]];
|
|
6
|
-
}
|
|
7
|
-
export declare function captureAuthority(input: AuthorityRequirementsInput | undefined): AuthorityRequirements | undefined;
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
import type { ResolvedCoreDefinition } from '../../platform/schema/index.js';
|
|
2
|
-
import type { AuthorityRequirementsInput } from './authority.js';
|
|
3
|
-
import type { ClassRequirementInput } from './classes.js';
|
|
4
|
-
import type { FunctionRequirementTarget } from './functions.js';
|
|
5
|
-
import type { CoreRequirement } from './requirement.js';
|
|
6
|
-
/** Capabilities assigned to one installation-owned local Core Identity. */
|
|
7
|
-
export interface CoreRequirementInput {
|
|
8
|
-
readonly subject: Pick<ResolvedCoreDefinition, 'ref'>;
|
|
9
|
-
/** Exact executable local callables or direct dependency callables; does not bypass Policies. */
|
|
10
|
-
readonly functions?: readonly FunctionRequirementTarget[];
|
|
11
|
-
readonly classes?: readonly ClassRequirementInput[];
|
|
12
|
-
readonly authority?: AuthorityRequirementsInput;
|
|
13
|
-
}
|
|
14
|
-
export declare function captureCore(input: readonly CoreRequirementInput[] | undefined): readonly CoreRequirement[];
|