@astrale-os/sdk 0.6.0-beta.28 → 0.6.0-beta.29

package/README.md

@@ -95,6 +95,66 @@ valid; the linter emits a non-failing `SCH-ICON-NEUTRAL` warning. Bare names suc
 non-canonical empty SVGs, external references, and executable SVG content are rejected during
 Schema authoring.
 
+## Read rules and caller rules
+
+Every concrete Class authored through the SDK declares who may read it, and every executable
+`authorized` callable declares who may call it. Omission is rejected by TypeScript and at the
+runtime authoring boundary. A rule is a predicate on the caller: a Policy, or its constant value
+`true` or `false`.
+
+```typescript
+import { classIcon, func, nodeClass } from '@astrale-os/sdk/schema'
+import { FileText, Lock } from '@astrale-os/sdk/schema/icons'
+import { z } from 'zod'
+
+export const Article = nodeClass({
+  icon: classIcon.lucide(FileText),
+  policies: { read: true },
+})
+
+export const Secret = nodeClass({
+  icon: classIcon.lucide(Lock),
+  policies: { read: false, traverse: false },
+})
+
+export const purge = func({
+  auth: 'authorized',
+  policy: false,
+  input: z.strictObject({}),
+  output: z.boolean(),
+})
+```
+
+A Class rule judges the caller, which passes by owning the Class's installation or by the rule,
+never by a capability it holds. When a Domain acts for a caller, the Domain must also hold its own
+right on the Class (the capability its requirements declare, or ownership), whatever the rule; an
+Identity acting for itself delegates nothing and meets no such ceiling. A callable reads the same
+way, except that its principal always holds its right (`can_use` or ownership). `true` admits
+every Identity of the instance, never an anonymous request.
+
+| Declared | Caller is admitted when |
+| --- | --- |
+| Class `read: true` | always |
+| Class `read: false` | it is the owning installation |
+| Class `read: aPolicy` | ownership or the Policy |
+| Callable `policy: false` | it is Root or the owning installation |
+| Callable `policy: true` | always |
+| Callable `policy: checks` | Root, ownership, or the checks |
+
+- `read: true` and `policy: false` are what an absent rule already meant. Writing them changes
+  neither the compiled Schema nor its revision.
+- An excluded caller stays denied: `true` holds only for a caller whose live composition is not
+  denied.
+- `read` governs values, `traverse` governs reachability: a Node is reachable, and its reference
+  selectable, when either rule admits the caller. A Class whose `read` is not `true` must
+  therefore declare `traverse` as well: `traverse: false` hides that its Nodes exist,
+  `traverse: true` keeps them reachable for every caller. Beside `read: true`, `traverse` stays
+  optional.
+- An abstract Class declares no rule. An abstract Method declares its caller rule only where a
+  concrete Class executes it.
+- `read: false`, `traverse: false` and `policy: true` need a Kernel that knows the two constants.
+  Earlier Kernels refuse such a Schema at installation.
+
 ## Business-error declarations
 
 Declare reusable business errors in `schema/modules/<module>/errors/` through the Schema facade:

package/dist/platform/schema/callable-authoring.d.ts

@@ -0,0 +1,21 @@
+import { func as kernelFunc, method as kernelMethod, type CallablePolicyBuilder, type FunctionInput, type Method, type MethodInput } from '@astrale-os/kernel-dsl/v1/builder';
+/** Who may call an authorized callable: Policy checks, or the constant `true` or `false`. */
+export type CallerRule = CallablePolicyBuilder | boolean;
+/**
+ * An executable `authorized` callable declares its caller rule. An abstract Method is a contract
+ * on an abstract Class and executable on a concrete one, so its rule is settled by the Class that
+ * declares it.
+ */
+export type DeclaredCallerRule<Config> = Config extends {
+    readonly auth: 'authorized';
+} ? Config extends {
+    readonly abstract: true;
+} ? unknown : {
+    readonly policy: CallerRule;
+} : unknown;
+/** Author a Function. An `authorized` Function declares its caller rule. */
+export declare function func<const Config extends FunctionInput>(config: Config & DeclaredCallerRule<Config>): ReturnType<typeof kernelFunc<Config>>;
+/** Author a Method. An executable `authorized` Method declares its caller rule. */
+export declare function method<const Config extends MethodInput>(config: Config & DeclaredCallerRule<Config>): ReturnType<typeof kernelMethod<Config>>;
+/** A concrete Class executes every Method it declares, abstract contracts included. */
+export declare function assertNoUndeclaredCallerRule(methods: Readonly<Record<string, Method>> | undefined): void;

package/dist/platform/schema/callable-authoring.js

@@ -0,0 +1,27 @@
+import { func as kernelFunc, method as kernelMethod, } from '@astrale-os/kernel-dsl/v1/builder';
+/** Authorized abstract Methods authored without a caller rule, until a Class declares them. */
+const undeclared = new WeakSet();
+export function func(config) {
+    if (config.auth === 'authorized' && config.policy === undefined)
+        undeclaredCallerRule('Function');
+    return kernelFunc(config);
+}
+export function method(config) {
+    const value = kernelMethod(config);
+    if (config.auth === 'authorized' && config.policy === undefined) {
+        if (config.abstract !== true)
+            undeclaredCallerRule('Method');
+        undeclared.add(value);
+    }
+    return value;
+}
+/** A concrete Class executes every Method it declares, abstract contracts included. */
+export function assertNoUndeclaredCallerRule(methods) {
+    for (const [name, value] of Object.entries(methods ?? {})) {
+        if (undeclared.has(value))
+            undeclaredCallerRule(`Method ${name}`);
+    }
+}
+function undeclaredCallerRule(subject) {
+    throw new TypeError(`${subject} is authorized and executable: declare its policy with Policy checks, true or false.`);
+}

package/dist/platform/schema/class-authoring.d.ts

@@ -1,36 +1,86 @@
-import { nodeClass as kernelNodeClass, type DirectedEdgeClass, type DirectedEdgeInput, type NodeClass, type NodeClassInput as KernelNodeClassInput, type UndirectedEdgeClass, type UndirectedEdgeInput } from '@astrale-os/kernel-dsl/v1/builder';
+import { edgeClass as kernelEdgeClass, nodeClass as kernelNodeClass, type DirectedEdgeClass, type DirectedEdgeInput, type Lazy, type NodeClass, type NodeClassInput as KernelNodeClassInput, type NodeClassPolicyInput, type Policy, type UndirectedEdgeClass, type UndirectedEdgeInput } from '@astrale-os/kernel-dsl/v1/builder';
 import { type ClassIcon } from './class-icon.js';
-/** SDK Node Class input: every author must make an explicit, admitted icon choice. */
+/**
+ * SDK Node Class input: every author must make an explicit, admitted icon choice, and every
+ * concrete Class must declare its read rule.
+ */
 export type NodeClassInput = Omit<KernelNodeClassInput, 'icon'> & {
     readonly icon: ClassIcon;
 };
+/** Who may read or traverse an Edge Class: a named Policy, or the constant `true` or `false`. */
+export type ClassReadRule = Lazy<Policy> | boolean;
+/**
+ * Who may read or traverse a Node Class: a named Policy, the constant `true` or `false`, or Policy
+ * checks over the observed Node (`self`) and fixed members (`ref(...)`), composed as the checks of
+ * an authorized callable.
+ */
+export type NodeClassReadRule = NodeClassPolicyInput;
+/**
+ * The observation rules of a concrete Class. A Node stays traversable through either rule, so a
+ * read rule other than `true` leaves every caller able to reach it, and to select its reference,
+ * until the traverse rule is declared too.
+ */
+export type DeclaredObservation<Rule = ClassReadRule> = {
+    readonly read: true;
+    readonly traverse?: Rule;
+} | {
+    readonly read: Exclude<Rule, true>;
+    readonly traverse: Rule;
+};
+/**
+ * A concrete Class declares its read rule, and its traverse rule whenever the read rule is not
+ * `true`. An abstract Class is never observed directly, so it declares neither.
+ */
+export type DeclaredReadRule<Config, Rule = ClassReadRule> = Config extends {
+    readonly abstract: true;
+} ? unknown : {
+    readonly policies: DeclaredObservation<Rule>;
+};
 /** Preserve authored input instead of serializing expanded inheritance projections in consumers. */
 export interface AuthoredNodeClass<Config extends NodeClassInput> extends ReturnType<typeof kernelNodeClass<Config>> {
 }
+type DirectedOptions = Omit<DirectedEdgeInput, 'orientation'>;
+type UndirectedOptions = Omit<UndirectedEdgeInput, 'orientation'>;
+/** The two states `defineClass` admits: abstract, or concrete with declared observation rules. */
+type Declared<Input, Rule = ClassReadRule> = (Input & {
+    readonly abstract: true;
+}) | (Input & {
+    readonly abstract: false;
+} & {
+    readonly policies: DeclaredObservation<Rule>;
+});
 type NodeInput = {
     readonly kind: 'node';
-    readonly abstract: boolean;
-} & NodeClassInput;
+} & Declared<NodeClassInput, NodeClassReadRule>;
 type DirectedInput = {
     readonly kind: 'edge';
     readonly orientation: 'directed';
-    readonly abstract: boolean;
-} & Omit<DirectedEdgeInput, 'orientation'>;
+} & Declared<DirectedOptions>;
 type UndirectedInput = {
     readonly kind: 'edge';
     readonly orientation: 'undirected';
-    readonly abstract: boolean;
-} & Omit<UndirectedEdgeInput, 'orientation'>;
+} & Declared<UndirectedOptions>;
 /**
  * Author a Node Class whose materialized configuration always carries an explicitly selected,
- * admitted SVG icon. The mapped input retains inference while expanding package-private
- * Config interface names into portable structure for downstream declaration emit.
+ * admitted SVG icon and, when concrete, a declared read rule. The mapped input retains inference
+ * while expanding package-private Config interface names into portable structure for downstream
+ * declaration emit.
  */
-export declare function nodeClass<const Config extends NodeClassInput>(config: Config & Record<Exclude<keyof Config, keyof NodeClassInput>, never>): AuthoredNodeClass<{
+export declare function nodeClass<const Config extends NodeClassInput>(config: Config & Record<Exclude<keyof Config, keyof NodeClassInput>, never> & DeclaredReadRule<Config, NodeClassReadRule>): AuthoredNodeClass<{
     [Key in keyof Config]: Key extends 'properties' | 'methods' | 'policies' ? {
         [Member in keyof NonNullable<Config[Key]>]: NonNullable<Config[Key]>[Member];
     } | Extract<Config[Key], undefined> : Key extends 'extends' ? Config[Key] extends infer Parents extends NodeClassInput['extends'] ? Parents extends readonly unknown[] ? readonly [...Parents] : Parents : never : Config[Key];
 }>;
+declare function directed<const Input extends DirectedOptions>(input: Input & Parameters<typeof kernelEdgeClass.directed<Input>>[0] & DeclaredReadRule<Input>): ReturnType<typeof kernelEdgeClass.directed<Input>>;
+declare function undirected<const Input extends UndirectedOptions>(input: Input & Parameters<typeof kernelEdgeClass.undirected<Input>>[0] & DeclaredReadRule<Input>): ReturnType<typeof kernelEdgeClass.undirected<Input>>;
+/**
+ * Author an Edge Class. A concrete Edge Class declares its read rule exactly as a Node Class
+ * does; the handle is the canonical DSL handle.
+ */
+export declare const edgeClass: Readonly<{
+    directed: typeof directed;
+    undirected: typeof undirected;
+}>;
 export declare function defineClass(config: NodeInput): NodeClass;
 export declare function defineClass(config: DirectedInput): DirectedEdgeClass;
 export declare function defineClass(config: UndirectedInput): UndirectedEdgeClass;

package/dist/platform/schema/class-authoring.js

@@ -1,20 +1,53 @@
-import { defineClass as defineKernelClass, nodeClass as kernelNodeClass, } from '@astrale-os/kernel-dsl/v1/builder';
+import { edgeClass as kernelEdgeClass, nodeClass as kernelNodeClass, } from '@astrale-os/kernel-dsl/v1/builder';
+import { assertNoUndeclaredCallerRule } from './callable-authoring.js';
 import { classIcon } from './class-icon.js';
 export function nodeClass(config) {
     if (config === undefined || config.icon === undefined) {
         throw new TypeError('Node Class icon is required; use classIcon.neutral to make an explicit neutral choice.');
     }
+    assertDeclaredReadRule('Node', config);
+    if (config.abstract !== true)
+        assertNoUndeclaredCallerRule(config.methods);
     return kernelNodeClass({
         ...config,
         icon: classIcon.svg(config.icon),
     });
 }
+function directed(input) {
+    assertDeclaredReadRule('Edge', input);
+    return kernelEdgeClass.directed(input);
+}
+function undirected(input) {
+    assertDeclaredReadRule('Edge', input);
+    return kernelEdgeClass.undirected(input);
+}
+/**
+ * Author an Edge Class. A concrete Edge Class declares its read rule exactly as a Node Class
+ * does; the handle is the canonical DSL handle.
+ */
+export const edgeClass = Object.freeze({ directed, undirected });
 export function defineClass(config) {
     if (config.kind === 'node') {
         const { kind: _, ...input } = config;
         return nodeClass(input);
     }
-    if (config.orientation === 'directed')
-        return defineKernelClass(config);
-    return defineKernelClass(config);
+    if (config.orientation === 'directed') {
+        const { kind: _, orientation: __, ...input } = config;
+        return edgeClass.directed(input);
+    }
+    const { kind: _, orientation: __, ...input } = config;
+    return edgeClass.undirected(input);
+}
+/** The authoring boundary restates the type contract for untyped and widened configurations. */
+function assertDeclaredReadRule(kind, config) {
+    if (config.abstract === true)
+        return;
+    const rule = kind === 'Node' ? 'a Policy, Policy checks, true or false' : 'a Policy, true or false';
+    const read = config.policies?.read;
+    if (read === undefined) {
+        throw new TypeError(`${kind} Class read rule is required; declare policies.read with ${rule}.`);
+    }
+    if (read !== true && config.policies?.traverse === undefined) {
+        throw new TypeError(`${kind} Class traverse rule is required when its read rule is not true; declare policies.traverse with ${rule}.`);
+    }
 }

package/dist/platform/schema/index.d.ts

@@ -7,14 +7,16 @@ export type { StateProperty } from './state-property.js';
 export { property } from './property.js';
 export type { AuthoredProperty, PropertyOptions } from './property.js';
 export { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
-export { defineClass, nodeClass } from './class-authoring.js';
-export type { AuthoredNodeClass, NodeClassInput } from './class-authoring.js';
+export { defineClass, edgeClass, nodeClass } from './class-authoring.js';
+export type { AuthoredNodeClass, ClassReadRule, DeclaredObservation, DeclaredReadRule, NodeClassReadRule, NodeClassInput, } from './class-authoring.js';
+export { func, method } from './callable-authoring.js';
+export type { CallerRule, DeclaredCallerRule } from './callable-authoring.js';
 export { error } from './error.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFamily } from './error.js';
 export { classIcon } from './class-icon.js';
 export type { ClassIcon } from './class-icon.js';
 export type { StoredPropertyInputOf } from './property-input.js';
-export type { CallablePolicyBuilder, CallablePolicyContext, CallableProjection, AuthoredMethodProjection, AuthoredPropertyProjection, ClassIdentityProjection, ClassOwnerProjection, CoreEdge, CoreEndpoint, CoreNode, DefinedSchema, DirectedEdgeClass, ClassReferenceProjection, ClassProjection, FunctionProjection, EdgeClass, Function, Method, MethodProjection, Lazy, NodeClass, Policy, PolicyExistsContext, PolicyNodeBinder, PolicyPatternContext, Property, PropertyProjection, ResolvedDomainOfInput, View, } from '@astrale-os/kernel-dsl/v1/builder';
+export type { CallablePolicyBuilder, CallablePolicyContext, ClassRuleBuilder, ClassRuleContext, PolicyCheckContext, CallableProjection, AuthoredMethodProjection, AuthoredPropertyProjection, ClassIdentityProjection, ClassOwnerProjection, CoreEdge, CoreEndpoint, CoreNode, DefinedSchema, DirectedEdgeClass, ClassReferenceProjection, ClassProjection, FunctionProjection, EdgeClass, Function, Method, MethodProjection, Lazy, NodeClass, Policy, PolicyExistsContext, PolicyNodeBinder, PolicyPatternContext, Property, PropertyProjection, ResolvedDomainOfInput, View, } from '@astrale-os/kernel-dsl/v1/builder';
 export type { Array, Object, Value } from '@astrale-os/kernel-dsl/value';
 export type { CallableExecution, ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, PropertyImmutability, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
 export type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';

package/dist/platform/schema/index.js

@@ -4,7 +4,8 @@ export { defineSchema } from './schema-authoring.js';
 export { stateProperty } from './state-property.js';
 export { property } from './property.js';
 export { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
-export { defineClass, nodeClass } from './class-authoring.js';
+export { defineClass, edgeClass, nodeClass } from './class-authoring.js';
+export { func, method } from './callable-authoring.js';
 export { error } from './error.js';
 export { classIcon } from './class-icon.js';
 /** Kernel-owned Schema values used by authored product Schemas and graph operations. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.6.0-beta.28",
+  "version": "0.6.0-beta.29",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -257,11 +257,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/kernel-client": "1.0.0-beta.1",
-    "@astrale-os/kernel-core": "1.0.0-beta.1",
-    "@astrale-os/kernel-dsl": "1.0.0-beta.1",
-    "@astrale-os/kernel-protocol": "1.0.0-beta.1",
-    "@astrale-os/kernel-server": "1.0.0-beta.1",
+    "@astrale-os/kernel-client": "1.0.0-beta.2",
+    "@astrale-os/kernel-core": "1.0.0-beta.2",
+    "@astrale-os/kernel-dsl": "1.0.0-beta.2",
+    "@astrale-os/kernel-protocol": "1.0.0-beta.2",
+    "@astrale-os/kernel-server": "1.0.0-beta.2",
     "@lucide/icons": "1.34.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "cross-spawn": "7.0.6",