@astrale-os/sdk 0.6.0-beta.56 → 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.
Files changed (74) hide show
  1. package/README.md +11 -10
  2. package/dist/application/index.d.ts +2 -1
  3. package/dist/application/query/execution/crossings.d.ts +6 -1
  4. package/dist/application/query/execution/crossings.js +15 -1
  5. package/dist/application/query/execution/legacy/declared-classes.d.ts +10 -0
  6. package/dist/application/query/execution/legacy/declared-classes.js +9 -0
  7. package/dist/application/requirements/canonical.d.ts +7 -0
  8. package/dist/application/requirements/canonical.js +16 -0
  9. package/dist/application/requirements/classes.d.ts +9 -7
  10. package/dist/application/requirements/classes.js +35 -42
  11. package/dist/application/requirements/functions.d.ts +3 -1
  12. package/dist/application/requirements/functions.js +12 -27
  13. package/dist/application/requirements/index.d.ts +34 -16
  14. package/dist/application/requirements/index.js +17 -20
  15. package/dist/application/requirements/legacy/authority.d.ts +21 -0
  16. package/dist/application/requirements/{authority.js → legacy/authority.js} +5 -2
  17. package/dist/application/requirements/legacy/classes.d.ts +22 -0
  18. package/dist/application/requirements/legacy/classes.js +24 -0
  19. package/dist/application/requirements/legacy/core.d.ts +30 -0
  20. package/dist/application/requirements/{core.js → legacy/core.js} +15 -13
  21. package/dist/application/requirements/legacy/functions.d.ts +7 -0
  22. package/dist/application/requirements/legacy/functions.js +15 -0
  23. package/dist/application/requirements/legacy/index.d.ts +43 -0
  24. package/dist/application/requirements/legacy/index.js +1 -0
  25. package/dist/application/requirements/legacy/requirements.d.ts +31 -0
  26. package/dist/application/requirements/legacy/requirements.js +31 -0
  27. package/dist/application/requirements/requirement.d.ts +30 -19
  28. package/dist/application/requirements/roles.d.ts +17 -0
  29. package/dist/application/requirements/roles.js +62 -0
  30. package/dist/application/requirements/scopes.d.ts +16 -0
  31. package/dist/application/requirements/scopes.js +34 -0
  32. package/dist/deployment/build/build.d.ts +3 -5
  33. package/dist/deployment/build/compile.js +12 -64
  34. package/dist/deployment/build/legacy/requirements.d.ts +11 -0
  35. package/dist/deployment/build/legacy/requirements.js +79 -0
  36. package/dist/deployment/build/material.js +0 -3
  37. package/dist/execution/invocation/dispatch/context.js +2 -1
  38. package/dist/platform/schema/class-authoring.d.ts +9 -7
  39. package/dist/platform/schema/class-authoring.js +3 -2
  40. package/dist/platform/schema/index.d.ts +1 -1
  41. package/dist/testing/query.js +2 -1
  42. package/dist/tooling/linter/adapters/typescript/discover.js +8 -2
  43. package/dist/tooling/linter/adapters/typescript/index.d.ts +6 -0
  44. package/dist/tooling/linter/adapters/typescript/index.js +1 -0
  45. package/dist/tooling/linter/adapters/typescript/legacy.d.ts +20 -0
  46. package/dist/tooling/linter/adapters/typescript/legacy.js +28 -0
  47. package/dist/tooling/linter/implementations/source/callable-requirements.d.ts +1 -2
  48. package/dist/tooling/linter/implementations/source/callable-requirements.js +7 -44
  49. package/dist/tooling/linter/implementations/source/const-initializer.d.ts +3 -0
  50. package/dist/tooling/linter/implementations/source/const-initializer.js +31 -0
  51. package/dist/tooling/linter/implementations/source/domain-requirements.d.ts +8 -0
  52. package/dist/tooling/linter/implementations/source/domain-requirements.js +35 -0
  53. package/dist/tooling/linter/implementations/source/global.js +21 -8
  54. package/dist/tooling/linter/implementations/source/legacy/requirements.d.ts +10 -0
  55. package/dist/tooling/linter/implementations/source/legacy/requirements.js +40 -0
  56. package/dist/tooling/linter/implementations/source/legacy-folders.d.ts +3 -0
  57. package/dist/tooling/linter/implementations/source/legacy-folders.js +126 -0
  58. package/dist/tooling/linter/implementations/source/mutations.js +7 -22
  59. package/dist/tooling/linter/implementations/source/requirement-entries.d.ts +24 -0
  60. package/dist/tooling/linter/implementations/source/requirement-entries.js +52 -0
  61. package/dist/tooling/linter/implementations/source/schema.d.ts +3 -0
  62. package/dist/tooling/linter/implementations/source/schema.js +9 -5
  63. package/dist/tooling/linter/implementations/source/tests.js +1 -1
  64. package/dist/tooling/linter/implementations/source/verifiers.js +2 -0
  65. package/dist/tooling/linter/policy/generated.js +2 -2
  66. package/dist/tooling/linter/requirements/registry.js +2 -0
  67. package/docs/accounts/scenarios.tsv +12 -0
  68. package/docs/handler-dependencies.md +5 -3
  69. package/docs/legacy.md +113 -0
  70. package/docs/queries.md +3 -2
  71. package/docs/requirements.md +134 -0
  72. package/package.json +2 -2
  73. package/dist/application/requirements/authority.d.ts +0 -7
  74. 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.56",
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",
@@ -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.1",
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[];