@kinotic-ai/idl 5.0.0-beta.1 → 5.0.0-beta.3

package/README.md

@@ -11,7 +11,7 @@ The type schema layer that makes Kinotic's cross-language RPC safe and consisten
 - **One schema, every language.** Define a data structure or service interface once in a language-neutral format — Java, TypeScript, and the platform all stay in sync automatically.
 - **No more integration surprises.** Schema contracts are enforced across the RPC boundary, catching mismatches at definition time rather than in production.
 - **Rich metadata, zero boilerplate.** Attach validation rules and behavioral decorators to your models without writing custom validators or annotation processors.
-- **Drives the whole platform.** OpenAPI specifications, GraphQL schemas, and serialization logic are all generated from the same IDL definitions — change once, update everywhere.
+- **Drives the whole platform.** Entity storage, entity services, and serialization logic are all derived from the same IDL definitions — change once, update everywhere.
 
 ---
 
@@ -21,7 +21,7 @@ The type schema layer that makes Kinotic's cross-language RPC safe and consisten
 Describe any data structure or service interface in a format that is not tied to any one language or runtime. The same definition drives both the Java server and the TypeScript client.
 
 ### Automatic API Generation
-Publish a schema and the platform generates OpenAPI endpoints, GraphQL types, and serialization mappings for you. There is no manual mapping layer to maintain.
+Publish a schema and the platform creates its backing storage, registers its services, and derives its serialization mappings for you. There is no manual mapping layer to maintain.
 
 ### Validation and Behavioral Metadata
 Annotate data models with constraints and behavioral hints directly in the schema. Validation rules travel with the definition instead of being scattered across your codebase.
@@ -39,13 +39,13 @@ Data moving between services is serialized and deserialized according to the sch
 `@kinotic-ai/idl` sits just above the core transport layer:
 
 ```
-@kinotic-ai/os-api      ← cloud OS management
+@kinotic-ai/management-api      ← cloud OS management
 @kinotic-ai/persistence ← schema-driven data access
 @kinotic-ai/idl         ← cross-language type schemas (this package)
 @kinotic-ai/core        ← connection & transport
 ```
 
-`@kinotic-ai/persistence` and `@kinotic-ai/os-api` both depend on the schema definitions this package provides. Start here when you need to describe data that crosses a service boundary.
+`@kinotic-ai/persistence` and `@kinotic-ai/management-api` both depend on the schema definitions this package provides. Start here when you need to describe data that crosses a service boundary.
 
 ---
 

package/dist/index.cjs

@@ -66,6 +66,9 @@ __export(exports_src, {
   C3Decorator: () => C3Decorator,
   ByteC3Type: () => ByteC3Type,
   BooleanC3Type: () => BooleanC3Type,
+  AuthzRoleDeclaration: () => AuthzRoleDeclaration,
+  AuthzResourceDecorator: () => AuthzResourceDecorator,
+  AuthzCheckDecorator: () => AuthzCheckDecorator,
   AsyncC3Type: () => AsyncC3Type,
   ArrayC3Type: () => ArrayC3Type,
   AnyC3Type: () => AnyC3Type
@@ -76,6 +79,43 @@ module.exports = __toCommonJS(exports_src);
 class C3Decorator {
   type = "";
 }
+
+// packages/idl/src/api/decorators/AuthzCheckDecorator.ts
+class AuthzCheckDecorator extends C3Decorator {
+  resource = null;
+  objectId = null;
+  permissionResource = null;
+  permission = null;
+  implies = [];
+  unchecked = false;
+  consistent = false;
+  constructor() {
+    super();
+    this.type = "AuthzCheck";
+  }
+}
+// packages/idl/src/api/decorators/AuthzResourceDecorator.ts
+class AuthzResourceDecorator extends C3Decorator {
+  resourceType;
+  parent = null;
+  objectId = null;
+  permission = null;
+  roles = [];
+  constructor(resourceType) {
+    super();
+    this.type = "AuthzResource";
+    this.resourceType = resourceType;
+  }
+}
+// packages/idl/src/api/decorators/AuthzRoleDeclaration.ts
+class AuthzRoleDeclaration {
+  id;
+  permissions;
+  constructor(id, permissions) {
+    this.id = id;
+    this.permissions = permissions;
+  }
+}
 // packages/idl/src/api/decorators/NotNullDecorator.ts
 class NotNullDecorator extends C3Decorator {
   constructor() {
@@ -376,12 +416,12 @@ class ServiceDefinition extends AbstractDefinition {
     super(name, decorators, metadata);
     this.namespace = namespace;
   }
-  functions = new Set;
+  functions = [];
   addFunction(func) {
-    if (this.functions.has(func)) {
+    if (this.functions.some((existing) => existing.name === func.name)) {
       throw new Error(`ServiceDefinition already contains function for name ${func.name}`);
     }
-    this.functions.add(func);
+    this.functions.push(func);
     return this;
   }
   getQualifiedName() {

package/dist/index.d.cts

@@ -7,6 +7,90 @@ declare class C3Decorator {
 	type: string;
 }
 /**
+* The authorization check a function requires. A service's definition declares what the derivation cannot
+* read from the function's name and parameters: a permission of its own, another object than the derived
+* one, the permissions it implies, a consistent answer, or that the function is served with no check. The
+* platform derives the rest when the service registers, naming the object checked and the type the permission
+* is named for.
+*/
+declare class AuthzCheckDecorator extends C3Decorator {
+	/**
+	* The type of the object the check is made on, when it is not the derived one.
+	*/
+	resource: string | null;
+	/**
+	* The id of the object the check is made on, as a template over the function's parameters and the
+	* caller's scope, such as `{reportId}` or `{@tenantId}`.
+	*/
+	objectId: string | null;
+	/**
+	* The type the permission is named for, which the platform derives.
+	*/
+	permissionResource: string | null;
+	/**
+	* The short permission name, such as `can_generate`.
+	*/
+	permission: string | null;
+	/**
+	* Short names of permissions on the permission's type that this one implies.
+	*/
+	implies: string[];
+	/**
+	* True for a function declared served with no check, which any caller the zone admits may call.
+	*/
+	unchecked: boolean;
+	/**
+	* Whether the check must answer from the stored relationships rather than the engine's caches.
+	*/
+	consistent: boolean;
+	constructor();
+}
+/**
+* A role a resource service declares beside the built-in ones, as the {@link AuthzResourceDecorator} carries
+* it: the role's id and the short names of the permissions of the type it bundles.
+*/
+declare class AuthzRoleDeclaration {
+	/**
+	* The role's id, `<type>.<level>`, such as `report.generator`.
+	*/
+	id: string;
+	/**
+	* Short names of the type's permissions the role bundles.
+	*/
+	permissions: string[];
+	constructor(id: string, permissions: string[]);
+}
+/**
+* Marks a service as acting on one authorization resource type: the service's functions are checked against
+* that type, and the type, with its containment parent and the roles it declares, is part of the generated
+* authorization model.
+*/
+declare class AuthzResourceDecorator extends C3Decorator {
+	/**
+	* The resource type the service acts on, such as `report`.
+	*/
+	resourceType: string;
+	/**
+	* The type that contains this one and from which grants inherit, or null for a root type.
+	*/
+	parent: string | null;
+	/**
+	* The object every function of the service is checked on, as a template over the caller's scope, unless the
+	* function declares its own; null when each function's object is derived from what it names.
+	*/
+	objectId: string | null;
+	/**
+	* The permission every function of the service requires unless it declares its own; null when each
+	* function's permission is derived from its name.
+	*/
+	permission: string | null;
+	/**
+	* The roles the service declares for its type beside the built-in ones; empty when it declares none.
+	*/
+	roles: AuthzRoleDeclaration[];
+	constructor(resourceType: string);
+}
+/**
 * Signifies that the decorated value must not be null
 * Created by Navíd Mitchell 🤪 on 4/23/23.
 */
@@ -331,10 +415,9 @@ declare class ServiceDefinition extends AbstractDefinition implements HasQualifi
 		[p: string]: any;
 	} | null);
 	/**
-	* This defines {@link FunctionDefinition}'s for this {@link ServiceDefinition}
-	* The key is the function name and the value is the schema that defines the function
+	* The {@link FunctionDefinition}s of this {@link ServiceDefinition}, in declaration order; no two share a name.
 	*/
-	functions: Set<FunctionDefinition>;
+	functions: FunctionDefinition[];
 	/**
 	* Stores the given value in the functions definitions for this schema
 	* If a schema for the name already exists an error will be thrown
@@ -470,4 +553,4 @@ declare class UnionC3Type extends ComplexC3Type {
 declare class VoidC3Type extends C3Type {
 	constructor();
 }
-export { VoidC3Type, UnionC3Type, StringC3Type, StreamC3Type, ShortC3Type, ServiceDefinition, ReferenceC3Type, PropertyDefinition, ParameterDefinition, ObjectC3Type, NotNullDecorator, NamespaceDefinition, MetadataType, MapC3Type, LongC3Type, IntC3Type, HasQualifiedName, HasMetadata, HasDecorators, FunctionDefinition, FloatC3Type, EnumC3Type, DoubleC3Type, DateC3Type, ComplexC3Type, CharC3Type, C3Type, C3Decorator, ByteC3Type, BooleanC3Type, AsyncC3Type, ArrayC3Type, AnyC3Type };
+export { VoidC3Type, UnionC3Type, StringC3Type, StreamC3Type, ShortC3Type, ServiceDefinition, ReferenceC3Type, PropertyDefinition, ParameterDefinition, ObjectC3Type, NotNullDecorator, NamespaceDefinition, MetadataType, MapC3Type, LongC3Type, IntC3Type, HasQualifiedName, HasMetadata, HasDecorators, FunctionDefinition, FloatC3Type, EnumC3Type, DoubleC3Type, DateC3Type, ComplexC3Type, CharC3Type, C3Type, C3Decorator, ByteC3Type, BooleanC3Type, AuthzRoleDeclaration, AuthzResourceDecorator, AuthzCheckDecorator, AsyncC3Type, ArrayC3Type, AnyC3Type };

package/dist/index.d.ts

@@ -7,6 +7,90 @@ declare class C3Decorator {
 	type: string;
 }
 /**
+* The authorization check a function requires. A service's definition declares what the derivation cannot
+* read from the function's name and parameters: a permission of its own, another object than the derived
+* one, the permissions it implies, a consistent answer, or that the function is served with no check. The
+* platform derives the rest when the service registers, naming the object checked and the type the permission
+* is named for.
+*/
+declare class AuthzCheckDecorator extends C3Decorator {
+	/**
+	* The type of the object the check is made on, when it is not the derived one.
+	*/
+	resource: string | null;
+	/**
+	* The id of the object the check is made on, as a template over the function's parameters and the
+	* caller's scope, such as `{reportId}` or `{@tenantId}`.
+	*/
+	objectId: string | null;
+	/**
+	* The type the permission is named for, which the platform derives.
+	*/
+	permissionResource: string | null;
+	/**
+	* The short permission name, such as `can_generate`.
+	*/
+	permission: string | null;
+	/**
+	* Short names of permissions on the permission's type that this one implies.
+	*/
+	implies: string[];
+	/**
+	* True for a function declared served with no check, which any caller the zone admits may call.
+	*/
+	unchecked: boolean;
+	/**
+	* Whether the check must answer from the stored relationships rather than the engine's caches.
+	*/
+	consistent: boolean;
+	constructor();
+}
+/**
+* A role a resource service declares beside the built-in ones, as the {@link AuthzResourceDecorator} carries
+* it: the role's id and the short names of the permissions of the type it bundles.
+*/
+declare class AuthzRoleDeclaration {
+	/**
+	* The role's id, `<type>.<level>`, such as `report.generator`.
+	*/
+	id: string;
+	/**
+	* Short names of the type's permissions the role bundles.
+	*/
+	permissions: string[];
+	constructor(id: string, permissions: string[]);
+}
+/**
+* Marks a service as acting on one authorization resource type: the service's functions are checked against
+* that type, and the type, with its containment parent and the roles it declares, is part of the generated
+* authorization model.
+*/
+declare class AuthzResourceDecorator extends C3Decorator {
+	/**
+	* The resource type the service acts on, such as `report`.
+	*/
+	resourceType: string;
+	/**
+	* The type that contains this one and from which grants inherit, or null for a root type.
+	*/
+	parent: string | null;
+	/**
+	* The object every function of the service is checked on, as a template over the caller's scope, unless the
+	* function declares its own; null when each function's object is derived from what it names.
+	*/
+	objectId: string | null;
+	/**
+	* The permission every function of the service requires unless it declares its own; null when each
+	* function's permission is derived from its name.
+	*/
+	permission: string | null;
+	/**
+	* The roles the service declares for its type beside the built-in ones; empty when it declares none.
+	*/
+	roles: AuthzRoleDeclaration[];
+	constructor(resourceType: string);
+}
+/**
 * Signifies that the decorated value must not be null
 * Created by Navíd Mitchell 🤪 on 4/23/23.
 */
@@ -331,10 +415,9 @@ declare class ServiceDefinition extends AbstractDefinition implements HasQualifi
 		[p: string]: any;
 	} | null);
 	/**
-	* This defines {@link FunctionDefinition}'s for this {@link ServiceDefinition}
-	* The key is the function name and the value is the schema that defines the function
+	* The {@link FunctionDefinition}s of this {@link ServiceDefinition}, in declaration order; no two share a name.
 	*/
-	functions: Set<FunctionDefinition>;
+	functions: FunctionDefinition[];
 	/**
 	* Stores the given value in the functions definitions for this schema
 	* If a schema for the name already exists an error will be thrown
@@ -470,4 +553,4 @@ declare class UnionC3Type extends ComplexC3Type {
 declare class VoidC3Type extends C3Type {
 	constructor();
 }
-export { VoidC3Type, UnionC3Type, StringC3Type, StreamC3Type, ShortC3Type, ServiceDefinition, ReferenceC3Type, PropertyDefinition, ParameterDefinition, ObjectC3Type, NotNullDecorator, NamespaceDefinition, MetadataType, MapC3Type, LongC3Type, IntC3Type, HasQualifiedName, HasMetadata, HasDecorators, FunctionDefinition, FloatC3Type, EnumC3Type, DoubleC3Type, DateC3Type, ComplexC3Type, CharC3Type, C3Type, C3Decorator, ByteC3Type, BooleanC3Type, AsyncC3Type, ArrayC3Type, AnyC3Type };
+export { VoidC3Type, UnionC3Type, StringC3Type, StreamC3Type, ShortC3Type, ServiceDefinition, ReferenceC3Type, PropertyDefinition, ParameterDefinition, ObjectC3Type, NotNullDecorator, NamespaceDefinition, MetadataType, MapC3Type, LongC3Type, IntC3Type, HasQualifiedName, HasMetadata, HasDecorators, FunctionDefinition, FloatC3Type, EnumC3Type, DoubleC3Type, DateC3Type, ComplexC3Type, CharC3Type, C3Type, C3Decorator, ByteC3Type, BooleanC3Type, AuthzRoleDeclaration, AuthzResourceDecorator, AuthzCheckDecorator, AsyncC3Type, ArrayC3Type, AnyC3Type };

package/dist/index.js

@@ -2,6 +2,43 @@
 class C3Decorator {
   type = "";
 }
+
+// packages/idl/src/api/decorators/AuthzCheckDecorator.ts
+class AuthzCheckDecorator extends C3Decorator {
+  resource = null;
+  objectId = null;
+  permissionResource = null;
+  permission = null;
+  implies = [];
+  unchecked = false;
+  consistent = false;
+  constructor() {
+    super();
+    this.type = "AuthzCheck";
+  }
+}
+// packages/idl/src/api/decorators/AuthzResourceDecorator.ts
+class AuthzResourceDecorator extends C3Decorator {
+  resourceType;
+  parent = null;
+  objectId = null;
+  permission = null;
+  roles = [];
+  constructor(resourceType) {
+    super();
+    this.type = "AuthzResource";
+    this.resourceType = resourceType;
+  }
+}
+// packages/idl/src/api/decorators/AuthzRoleDeclaration.ts
+class AuthzRoleDeclaration {
+  id;
+  permissions;
+  constructor(id, permissions) {
+    this.id = id;
+    this.permissions = permissions;
+  }
+}
 // packages/idl/src/api/decorators/NotNullDecorator.ts
 class NotNullDecorator extends C3Decorator {
   constructor() {
@@ -302,12 +339,12 @@ class ServiceDefinition extends AbstractDefinition {
     super(name, decorators, metadata);
     this.namespace = namespace;
   }
-  functions = new Set;
+  functions = [];
   addFunction(func) {
-    if (this.functions.has(func)) {
+    if (this.functions.some((existing) => existing.name === func.name)) {
       throw new Error(`ServiceDefinition already contains function for name ${func.name}`);
     }
-    this.functions.add(func);
+    this.functions.push(func);
     return this;
   }
   getQualifiedName() {
@@ -368,6 +405,9 @@ export {
   C3Decorator,
   ByteC3Type,
   BooleanC3Type,
+  AuthzRoleDeclaration,
+  AuthzResourceDecorator,
+  AuthzCheckDecorator,
   AsyncC3Type,
   ArrayC3Type,
   AnyC3Type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinotic-ai/idl",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.3",
   "type": "module",
   "files": [
     "dist"