@astrale-os/sdk 0.5.0-beta.115 → 0.5.0-beta.116

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0-beta.116](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.115...sdk-v0.5.0-beta.116) (2026-09-05)
+
+
+### Features
+
+* **app:** support sameNode policies and explicit Dataset references ([#432](https://github.com/astrale-os/sdk/issues/432)) ([29e72b3](https://github.com/astrale-os/sdk/commit/29e72b377c71f1e8cce8ce75a8a0d3920e4c46c6))
+
 ## [0.5.0-beta.115](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.114...sdk-v0.5.0-beta.115) (2026-09-05)
 
 

package/README.md

@@ -131,6 +131,28 @@ linter tool failures.
 Structured review [issues](issues/README.md) retain observation-first evidence and later governance
 attachments without becoming current contract authority.
 
+## Dataset references
+
+A Dataset can materialize a projected Node explicitly with `ref`, using its resolved local or
+direct-dependency definition:
+
+```typescript
+const demo = defineDataset(Schema, {
+  id: 'demo',
+  graph({ domain, ref }) {
+    const member = ref(domain.core.nodes.member)
+    // Repeating ref returns the same Dataset Node. node() always creates a separate identity.
+    return { member }
+  },
+})
+```
+
+`ref` uses the canonical symbolic Schema projection for Class, Function, Policy, View and Core
+facts. The Dataset's `references` table retains the explicit association between each projected
+NodePath and its Dataset Node ID through encoding and decoding. Matching properties or slugs do
+not create that association. Studio uses it when simulating `sameNode` and reference endpoints;
+a missing association makes that simulation unavailable.
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) for details.

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

@@ -7,7 +7,7 @@ export { classIcon } from './class-icon.js';
 export type { ClassIcon } from './class-icon.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 { Array, Object, Value } from '@astrale-os/kernel-dsl/value';
-export type { ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PropertyFacet, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
+export type { ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
 export type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
 /** Kernel-owned Schema values used by authored product Schemas and graph operations. */
 export { AuthorityOperationOrder, AuthorityOperations, AuthorityRelations, K, KernelRootFunctions, OperationCore, operationOf, } from '@astrale-os/kernel-core/schema';

package/dist/testing/dataset/builder.d.ts

@@ -1,7 +1,8 @@
 import type { Edge } from '../../platform/graph/edge/index.js';
 import type { Node, NodeId } from '../../platform/graph/node/index.js';
 import type { PropertyInputOf, ResolvedClass, schema } from '../../platform/schema/index.js';
-import type { DatasetNode } from './dataset.js';
+import type { DatasetNode, DatasetReferences } from './dataset.js';
+import { type DatasetReferenceInput } from './references.js';
 /** Resolved Classes of the exact authored Schema, keyed by their authored names. */
 export type DatasetClasses<Schema extends schema.DomainSchema> = schema.DomainOf<Schema>['classes'];
 /** One Dataset Node, or one Node identity that names a Node already added to the same Dataset. */
@@ -20,10 +21,13 @@ export interface DatasetGraph<Schema extends schema.DomainSchema> {
     /** The exact resolved Domain, including dependency Domains under their authored aliases. */
     readonly domain: schema.DomainOf<Schema>;
     readonly classes: DatasetClasses<Schema>;
+    /** Materialize one local or direct-dependency projected Node, retaining its reference identity. */
+    ref(input: DatasetReferenceInput): DatasetNode;
     node<Class extends ResolvedClass<'node'>>(definition: Class, input?: DatasetNodeInput<Class>): DatasetNode<Class>;
     edge<Class extends ResolvedClass<'edge'>>(definition: Class, source: DatasetEndpoint, target: DatasetEndpoint, input?: DatasetEdgeInput<Class>): Edge;
 }
 export interface DatasetFacts {
+    readonly references: DatasetReferences;
     readonly nodes: readonly Node[];
     readonly edges: readonly Edge[];
     /** Exact Node values handed out by `node()`, for variable admission by identity. */
@@ -35,4 +39,4 @@ export interface DatasetGraphSession<Schema extends schema.DomainSchema> {
     seal(): DatasetFacts;
 }
 /** Open one authoring session over a resolved Domain. Authored facts stay un-admitted until sealed. */
-export declare function openDatasetGraph<Schema extends schema.DomainSchema>(domain: schema.DomainOf<Schema>): DatasetGraphSession<Schema>;
+export declare function openDatasetGraph<Schema extends schema.DomainSchema>(domain: schema.ResolvedDomainOf<Schema>): DatasetGraphSession<Schema>;

package/dist/testing/dataset/builder.js

@@ -1,6 +1,8 @@
 import { edge as graphEdge, EdgeSlug } from '../../platform/graph/edge/index.js';
 import { node as graphNode, NodeId as admitNodeId } from '../../platform/graph/node/index.js';
+import { Path } from '../../platform/graph/path/index.js';
 import { ClassKey } from '../../platform/schema/index.js';
+import { datasetReferenceNodes } from './references.js';
 /** Open one authoring session over a resolved Domain. Authored facts stay un-admitted until sealed. */
 export function openDatasetGraph(domain) {
     const nodes = [];
@@ -8,10 +10,35 @@ export function openDatasetGraph(domain) {
     const byId = new Map();
     const created = new Set();
     const ordinals = new Map();
+    const references = {};
+    let projected;
+    let referenceOrdinal = 0;
     let sealed = false;
     const graph = Object.freeze({
         domain,
         classes: domain.classes,
+        ref(input) {
+            open();
+            const ref = 'ref' in input ? input.ref : input;
+            const path = Path.project(ref).raw;
+            const existing = references[path];
+            if (existing !== undefined)
+                return byId.get(existing);
+            projected ??= datasetReferenceNodes(domain);
+            const facts = projected.get(path);
+            if (facts === undefined)
+                throw new TypeError(`Dataset reference ${path} is not local or a direct dependency member.`);
+            let id;
+            do {
+                id = admitNodeId(`reference-${++referenceOrdinal}`);
+            } while (byId.has(id));
+            const value = graphNode({ id, class: facts.class, props: facts.props });
+            nodes.push(value);
+            byId.set(id, value);
+            created.add(value);
+            references[path] = id;
+            return value;
+        },
         node(definition, input = {}) {
             open();
             acceptClass(definition, 'node');
@@ -52,6 +79,7 @@ export function openDatasetGraph(domain) {
                 nodes: Object.freeze([...nodes]),
                 edges: Object.freeze([...edges]),
                 created,
+                references: Object.freeze({ ...references }),
             });
         },
     });

package/dist/testing/dataset/codec.js

@@ -4,6 +4,7 @@ import { schema as schemaApi } from '../../platform/schema/index.js';
 import { admitDatasetGraph } from './admission.js';
 import { DATASET_FORMAT, DATASET_VERSION } from './dataset.js';
 import { admitId, admitText, admitVariableName, assembleDataset } from './define.js';
+import { decodeDatasetReferences } from './references.js';
 /** Encode exact portable Dataset bytes without retaining runtime object identity. */
 export function encodeDataset(dataset) {
     const variables = Object.freeze(Object.fromEntries(Object.entries(dataset.variables)
@@ -21,13 +22,24 @@ export function encodeDataset(dataset) {
         }),
         graph: GraphData.encode({ nodes: dataset.nodes, edges: dataset.edges }),
         variables,
+        references: dataset.references,
     });
 }
 /** Decode one portable Dataset and re-admit its facts against the exact authored Schema. */
 export function decodeDataset(source, input) {
     if (!isRecord(input))
         invalid('Dataset must be an object.');
-    exactKeys(input, ['format', 'version', 'id', 'title', 'description', 'domain', 'graph', 'variables'], ['format', 'version', 'id', 'domain', 'graph', 'variables'], 'Dataset');
+    exactKeys(input, [
+        'format',
+        'version',
+        'id',
+        'title',
+        'description',
+        'domain',
+        'graph',
+        'variables',
+        'references',
+    ], ['format', 'version', 'id', 'domain', 'graph', 'variables', 'references'], 'Dataset');
     if (input.format !== DATASET_FORMAT || input.version !== DATASET_VERSION) {
         invalid('Dataset format or version is unsupported.');
     }
@@ -47,7 +59,8 @@ export function decodeDataset(source, input) {
     const domain = schemaApi.resolve(source);
     const graph = admitDatasetGraph(id, domain, GraphData.decode(input.graph));
     const variables = decodeVariables(input.variables, graph);
-    return assembleDataset({ schema: source, id, title, description, graph, variables });
+    const references = decodeDatasetReferences(input.references, domain, graph);
+    return assembleDataset({ schema: source, id, title, description, graph, variables, references });
 }
 function encodeVariable(value) {
     return Array.isArray(value)

package/dist/testing/dataset/dataset.d.ts

@@ -1,6 +1,6 @@
 import type { Graph, GraphDataJson } from '../../platform/graph/document/index.js';
 import type { Edge } from '../../platform/graph/edge/index.js';
-import type { Node } from '../../platform/graph/node/index.js';
+import type { Node, NodeId } from '../../platform/graph/node/index.js';
 import type { ResolvedClass, schema } from '../../platform/schema/index.js';
 export declare const DATASET_FORMAT: 'astrale.sdk.dataset';
 export declare const DATASET_VERSION: 1;
@@ -9,6 +9,8 @@ declare const DATASET_NODE_CLASS: unique symbol;
 export type DatasetNode<Class extends ResolvedClass<'node'> = ResolvedClass<'node'>> = Node & {
     readonly [DATASET_NODE_CLASS]: Class;
 };
+/** Canonical projected NodePath → explicit Dataset Node identity. */
+export type DatasetReferences = Readonly<Record<string, NodeId>>;
 export type DatasetVariable = DatasetNode | readonly DatasetNode[];
 export type DatasetVariables = Readonly<Record<string, DatasetVariable>>;
 /**
@@ -27,6 +29,7 @@ export interface Dataset<Schema extends schema.DomainSchema = schema.DomainSchem
     readonly nodes: readonly Node[];
     readonly edges: readonly Edge[];
     /** Named entry points into the facts, for tooling and tests. */
+    readonly references: DatasetReferences;
     readonly variables: Variables;
 }
 export type DatasetVariableJson = {
@@ -46,6 +49,7 @@ export interface DatasetJson {
         readonly revision: string;
     };
     readonly graph: GraphDataJson;
+    readonly references: Readonly<Record<string, string>>;
     readonly variables: Readonly<Record<string, DatasetVariableJson>>;
 }
 export type SchemaOfDataset<Value> = Value extends {

package/dist/testing/dataset/define.d.ts

@@ -1,7 +1,7 @@
 import type { Graph } from '../../platform/graph/document/index.js';
 import type { schema as schemaLanguage } from '../../platform/schema/index.js';
 import type { DatasetGraph } from './builder.js';
-import type { Dataset, DatasetVariables } from './dataset.js';
+import type { Dataset, DatasetReferences, DatasetVariables } from './dataset.js';
 /** Variables returned by one graph author; `void` means the Dataset names no entry point. */
 export type AuthoredDatasetVariables = DatasetVariables | void;
 /** The exact variables record retained by a Dataset for one authored return type. */
@@ -25,6 +25,7 @@ export declare function assembleDataset<Schema extends schemaLanguage.DomainSche
     readonly title: string | undefined;
     readonly description: string | undefined;
     readonly graph: Graph;
+    readonly references: DatasetReferences;
     readonly variables: DatasetVariables;
 }): Dataset<Schema>;
 export declare function admitId(input: unknown): string;

package/dist/testing/dataset/define.js

@@ -22,7 +22,15 @@ export function defineDataset(source, input) {
     const facts = session.seal();
     const graph = admitDatasetGraph(id, domain, { nodes: facts.nodes, edges: facts.edges });
     const variables = admitVariables(returned, facts.created, graph);
-    return assembleDataset({ schema: source, id, title, description, graph, variables });
+    return assembleDataset({
+        schema: source,
+        id,
+        title,
+        description,
+        graph,
+        variables,
+        references: facts.references,
+    });
 }
 /** True only for a Dataset produced by defineDataset or decodeDataset in this SDK package root. */
 export function isDataset(input) {
@@ -41,6 +49,7 @@ export function assembleDataset(input) {
         nodes: data.nodes,
         edges: data.edges,
         variables: input.variables,
+        references: input.references,
     });
     admittedDatasets.add(dataset);
     return dataset;

package/dist/testing/dataset/index.d.ts

@@ -2,6 +2,7 @@ export { DatasetAdmissionError } from './admission.js';
 export type { DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetNodeInput, } from './builder.js';
 export { decodeDataset, encodeDataset } from './codec.js';
 export { DATASET_FORMAT, DATASET_VERSION } from './dataset.js';
-export type { Dataset, DatasetJson, DatasetNode, DatasetVariable, DatasetVariableJson, DatasetVariables, SchemaOfDataset, } from './dataset.js';
+export type { Dataset, DatasetJson, DatasetNode, DatasetReferences, DatasetVariable, DatasetVariableJson, DatasetVariables, SchemaOfDataset, } from './dataset.js';
 export { defineDataset, isDataset } from './define.js';
 export type { AuthoredDatasetVariables, DatasetInput, DatasetVariablesOf } from './define.js';
+export type { DatasetReferenceInput } from './references.js';

package/dist/testing/dataset/references.d.ts

@@ -0,0 +1,13 @@
+import type { Graph } from '../../platform/graph/document/index.js';
+import type { Node } from '../../platform/graph/node/index.js';
+import type { PolicyObjectRef, schema } from '../../platform/schema/index.js';
+import type { DatasetReferences } from './dataset.js';
+export type DatasetReferenceInput = PolicyObjectRef | {
+    readonly ref: PolicyObjectRef;
+};
+type ReferenceNode = Pick<Node, 'class' | 'props'>;
+/** Symbolic projection supplies facts; only an explicit Dataset reference supplies identity. */
+export declare function datasetReferenceNodes(domain: schema.ResolvedDomainOf<schema.DomainSchema>): ReadonlyMap<string, ReferenceNode>;
+/** Serialized reference associations lose their proof and must match the exact projection again. */
+export declare function decodeDatasetReferences(input: unknown, domain: schema.ResolvedDomainOf<schema.DomainSchema>, graph: Graph): DatasetReferences;
+export {};

package/dist/testing/dataset/references.js

@@ -0,0 +1,56 @@
+import { graph as schemaGraph } from '@astrale-os/kernel-core/schema';
+import { isNodeId } from '../../platform/graph/node/index.js';
+import { Path } from '../../platform/graph/path/index.js';
+import { bundle, schema as schemaApi } from '../../platform/schema/index.js';
+/** Symbolic projection supplies facts; only an explicit Dataset reference supplies identity. */
+export function datasetReferenceNodes(domain) {
+    const result = new Map();
+    const direct = new Set([
+        domain.origin,
+        ...Object.values(domain.dependencies).map(({ origin }) => origin),
+    ]);
+    const sourceBundle = bundle.create(domain.source);
+    for (const source of [sourceBundle.root, ...sourceBundle.closure]) {
+        if (!direct.has(source.origin))
+            continue;
+        const owner = schemaApi.resolve(source);
+        const projection = schemaGraph.project(owner);
+        const allowed = new Set(owner
+            .definitions()
+            .filter(({ ref }) => ref.origin === owner.origin &&
+            ['class', 'function', 'policy', 'view', 'core'].includes(ref.kind))
+            .map(({ ref }) => Path.project(ref).raw));
+        for (const part of [projection.managed, projection.core]) {
+            for (const node of part.graph.nodes) {
+                if (!('as' in node))
+                    continue;
+                const path = part.paths.get(node.as);
+                if (path !== undefined && allowed.has(path))
+                    result.set(path, node);
+            }
+        }
+    }
+    return result;
+}
+/** Serialized reference associations lose their proof and must match the exact projection again. */
+export function decodeDatasetReferences(input, domain, graph) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Dataset references must be an object.');
+    }
+    const entries = Object.entries(input);
+    const projected = entries.length === 0 ? new Map() : datasetReferenceNodes(domain);
+    const identities = new Set();
+    for (const [path, id] of entries) {
+        const expected = projected.get(path);
+        const actual = isNodeId(id) ? graph.nodes.byId(id) : undefined;
+        if (expected === undefined ||
+            actual === undefined ||
+            identities.has(actual.id) ||
+            expected.class !== actual.class ||
+            JSON.stringify(expected.props) !== JSON.stringify(actual.props)) {
+            throw new TypeError(`Dataset reference ${path} does not identify its projected Node.`);
+        }
+        identities.add(actual.id);
+    }
+    return Object.freeze(Object.fromEntries(entries));
+}

package/dist/testing/index.d.ts

@@ -1,6 +1,6 @@
 /** Development and test resources: schema-admitted demo Datasets and their lazy project references. */
 export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
-export type { AuthoredDatasetVariables, Dataset, DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetInput, DatasetJson, DatasetNode, DatasetNodeInput, DatasetVariable, DatasetVariableJson, DatasetVariables, DatasetVariablesOf, SchemaOfDataset, } from './dataset/index.js';
+export type { AuthoredDatasetVariables, Dataset, DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetInput, DatasetJson, DatasetNode, DatasetNodeInput, DatasetReferences, DatasetReferenceInput, DatasetVariable, DatasetVariableJson, DatasetVariables, DatasetVariablesOf, SchemaOfDataset, } from './dataset/index.js';
 export { loadDataset, loadDatasets } from './load.js';
 export type { DatasetModuleLoader, LoadedDataset } from './load.js';
 export { dataset, isDatasetReference } from './reference.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.115",
+  "version": "0.5.0-beta.116",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -229,11 +229,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/kernel-client": "0.6.0-beta.49",
-    "@astrale-os/kernel-core": "0.9.0-beta.37",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.28",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.40",
-    "@astrale-os/kernel-server": "0.5.0-beta.42",
+    "@astrale-os/kernel-client": "0.6.0-beta.51",
+    "@astrale-os/kernel-core": "0.9.0-beta.39",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.30",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.42",
+    "@astrale-os/kernel-server": "0.5.0-beta.44",
     "@lucide/icons": "1.34.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "hono": "^4.13.2",