@astrale-os/sdk 0.6.0-beta.1 → 0.6.0-beta.3

package/README.md

@@ -213,6 +213,21 @@ Disabled rules are skipped before evaluation and remain visible in lint coverage
 project rule disable does not bypass generic Oxlint, project admission, type-universe checks, or
 linter tool failures.
 
+A committed tree that is not Domain source, such as client mockups or a preview harness, can be
+excluded from `astrale-domain lint` with root-relative globs:
+
+```json
+{
+  "ignore": ["mockups/**", "prototypes/**"]
+}
+```
+
+Ignored paths are pruned before discovery: they are never read, parsed, counted against source
+limits, included in the source snapshot digest, or passed to generic Oxlint. Each glob starts with a
+literal root entry and may use `*` and `?` within a segment and `**` as a whole segment; a matched
+directory excludes everything below it. A glob that would cover a declared layer (including a
+remapped `sourcePath`) or a governed root file is rejected, so `ignore` cannot bypass the layout.
+
 Structured review [issues](issues/README.md) retain observation-first evidence and later governance
 attachments without becoming current contract authority.
 
@@ -246,6 +261,54 @@ URL, size, and ETag checks. Concurrent publication and snapshot observations sha
 cancelling one observer does not cancel another. `session.snapshot()` remains the complete,
 coherent Publication, bundle, and View catalog observation.
 
+## Headless scripts and Domain callables
+
+Function admission requires the principal itself to be able to use the Function. A credential
+minted for a user or key, such as `astrale token`, carries that identity as principal: it passes
+Kernel callables, but a Domain callable that the identity reaches only through a Policy fails with
+`2004`. The Session `exchange` option presents each Domain callable with a credential its declaring
+Domain exchanged for the caller instead. The Domain becomes the principal, and the Policy is still
+evaluated against the caller. Kernel callables, including graph reads and writes, keep the source
+credential.
+
+```ts
+import { connect, createSessionCredentialProvider } from '@astrale-os/sdk/client/session'
+
+const session = connect({
+  url: 'https://instance.example/api',
+  auth: createSessionCredentialProvider({
+    ttlSeconds: 60,
+    // Return { credential, expiresAt } with expiresAt in Unix milliseconds.
+    mint: (signal) => mintSourceCredential(signal),
+  }),
+  exchange: {},
+})
+
+await session.call({ target: '/:orders.example:class.Order:create', input }) // Domain callable
+await session.graph.get('@order-id') // Kernel callable: the source credential
+```
+
+- **Hold the source in a provider.** Domain credentials are cached per source credential, so a
+  `resolve` that returns a new token on every call also exchanges on every call. The provider also
+  lets the Session renew a source that is too close to expiry to feed a Domain credential.
+- **Lifetimes.** `exchange.ttlSeconds` (default 300) must exceed the provider's `ttlSeconds` plus a
+  5-second settlement skew. A Domain credential never outlives its source.
+- **Reading as a Domain.** To call Kernel callables as a Domain, for example to read Shell-owned
+  Classes, feed a second Session from an explicit exchange:
+  `createSessionCredentialProvider({ ttlSeconds: 60, mint: (signal) => session.exchange(shellIssuer, { signal }) })`.
+  `session.exchange(issuer)` caches nothing.
+- **Current identity.** Use `session.auth.whoami()`; `@self` is a CLI shorthand.
+- **Failures.** A failed exchange raises `ExchangeError` from `@astrale-os/sdk/client`. Its
+  `failure` names the reason (`discovery`, `unsupported`, `unavailable`, `rejected`,
+  `invalid-response` or `source-exhausted`); a `rejected` error carries the Domain's public error
+  as its cause. Branch on `failure`, not on the message.
+
+| Credential presented | Principal | Kernel callable | Domain callable reached by Policy |
+| --- | --- | --- | --- |
+| Source credential (minted or key) | the identity | ✅ | ❌ `2004`, unless the identity holds `can_use` on it through a Group |
+| Session with `exchange` | the declaring Domain, for Domain callables | ✅ with the source credential | ✅ Policy evaluated against the identity |
+| `session.exchange(issuer)` held by a second Session | that Domain | ✅ as that Domain | only what that Domain may use |
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) for details.

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

@@ -13,6 +13,7 @@ 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 { Array, Object, Value } from '@astrale-os/kernel-dsl/value';
 export type { ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';

package/dist/platform/schema/property-input.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedPropertyCollection } from '@astrale-os/kernel-dsl/v1/language';
+type StoredValueOf<Property> = Property extends {
+    readonly __value?: infer Value;
+} ? Value : never;
+/** Values already held by graph Properties, including a blob's Ref rather than its write receipt. */
+export type StoredPropertyInputOf<Class> = Class extends {
+    readonly properties: infer Collection;
+} ? Collection extends {
+    readonly byKey: infer ByKey;
+} ? Readonly<{
+    [Key in keyof ByKey]?: StoredValueOf<ByKey[Key]>;
+} & {
+    [Name in Exclude<keyof Collection, keyof ResolvedPropertyCollection>]?: StoredValueOf<Collection[Name]>;
+}> : never : never;
+export {};

package/dist/platform/schema/property-input.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,6 +1,6 @@
 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 { ResolvedClass, schema, StoredPropertyInputOf } from '../../platform/schema/index.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. */
@@ -10,11 +10,11 @@ export type DatasetEndpoint = Node | NodeId | string;
 export interface DatasetNodeInput<Class extends ResolvedClass<'node'>> {
     /** Stable identity within the Dataset; derived from the Class name and insertion order when omitted. */
     readonly id?: string;
-    readonly props?: PropertyInputOf<Class>;
+    readonly props?: StoredPropertyInputOf<Class>;
 }
 export interface DatasetEdgeInput<Class extends ResolvedClass<'edge'>> {
     readonly slug?: string;
-    readonly props?: PropertyInputOf<Class>;
+    readonly props?: StoredPropertyInputOf<Class>;
 }
 /** Graph authoring surface handed to one Dataset definition. Facts are canonical Kernel values. */
 export interface DatasetGraph<Schema extends schema.DomainSchema> {

package/dist/tooling/linter/adapters/typescript/discover.d.ts

@@ -1,3 +1,3 @@
-import type { DomainPolicy } from '../../policy/index.js';
+import type { DomainLintIgnore, DomainPolicy } from '../../policy/index.js';
 import type { SourceProject } from './index.js';
-export declare function discoverProject(root: string, policy: DomainPolicy, signal?: AbortSignal): Promise<SourceProject>;
+export declare function discoverProject(root: string, policy: DomainPolicy, signal?: AbortSignal, ignore?: DomainLintIgnore): Promise<SourceProject>;

package/dist/tooling/linter/adapters/typescript/discover.js

@@ -25,7 +25,7 @@ const MAX_FILE_BYTES = 2 * 1024 * 1024;
 const MAX_TOTAL_BYTES = 128 * 1024 * 1024;
 const READ_CONCURRENCY = 32;
 const MAX_CONFIG_BYTES = 1024 * 1024;
-export async function discoverProject(root, policy, signal) {
+export async function discoverProject(root, policy, signal, ignore) {
     ensureActive(signal);
     const requestedRoot = resolve(root);
     let projectRoot;
@@ -46,7 +46,7 @@ export async function discoverProject(root, policy, signal) {
     const layerPaths = policy.layers.map(({ sourcePath }) => sourcePath.replace(/\/$/, ''));
     const paths = [];
     try {
-        await collect(projectRoot, projectRoot, paths, configuration.workspacePatterns, layerPaths, toolingPaths, 0, signal);
+        await collect(projectRoot, projectRoot, paths, configuration.workspacePatterns, layerPaths, toolingPaths, ignore, 0, signal);
     }
     catch (cause) {
         if (cause instanceof LinterToolError)
@@ -128,12 +128,19 @@ function digestField(hash, value) {
     hash.update(length);
     hash.update(value);
 }
-async function collect(root, directory, output, workspacePatterns, layerPaths, toolingPaths, depth, signal) {
+async function collect(root, directory, output, workspacePatterns, layerPaths, toolingPaths, ignore, depth, signal) {
     ensureActive(signal);
     const entries = await readdir(directory, { withFileTypes: true });
     for (const entry of entries) {
         const path = join(directory, entry.name);
         const projectPath = normalize(relative(root, path));
+        if (entry.isDirectory() && entry.name === '.spec') {
+            invalidProject(`Domain projects cannot own .spec directories; Kernel is the specification owner (${projectPath}).`);
+        }
+        // Project-ignored paths are pruned before any read, so their contents are
+        // neither parsed, counted against admission limits, nor digested.
+        if (ignore?.matches(projectPath))
+            continue;
         if (entry.isSymbolicLink()) {
             if (!IGNORED.has(entry.name)) {
                 invalidProject(`Domain compilation scope contains symbolic link ${relative(root, path)}.`);
@@ -141,16 +148,13 @@ async function collect(root, directory, output, workspacePatterns, layerPaths, t
             continue;
         }
         if (entry.isDirectory()) {
-            if (entry.name === '.spec') {
-                invalidProject(`Domain projects cannot own .spec directories; Kernel is the specification owner (${projectPath}).`);
-            }
             if (!IGNORED.has(entry.name)) {
                 if (await isWorkspaceMember(path, projectPath, workspacePatterns, layerPaths, signal))
                     continue;
                 if (depth >= MAX_DEPTH) {
                     invalidProject(`Domain source tree exceeds maximum depth ${MAX_DEPTH} at ${path}.`);
                 }
-                await collect(root, path, output, workspacePatterns, layerPaths, toolingPaths, depth + 1, signal);
+                await collect(root, path, output, workspacePatterns, layerPaths, toolingPaths, ignore, depth + 1, signal);
             }
             continue;
         }

package/dist/tooling/linter/implementations/source/global.js

@@ -86,7 +86,7 @@ export const globalRules = [
             return production(project).flatMap((file) => {
                 if (file.layer || governedRoots.has(file.path))
                     return [];
-                const evidence = `Production source ${file.path} is outside every declared layer and governed root.`;
+                const evidence = `Production source ${file.path} is outside every declared layer and governed root. Move Domain source into a declared layer; exclude a directory that is not Domain source, such as mockups, with an "ignore" glob in astrale.lint.json.`;
                 const anchor = file.source.statements[0];
                 return anchor ? [violation(file, anchor, evidence)] : [{ kind: 'violation', evidence }];
             });

package/dist/tooling/linter/lint.js

@@ -21,11 +21,11 @@ async function lintAstraleDomain(options) {
     }), { disabledRuleIds: configured.disabled.map(({ ruleId }) => ruleId) });
     evaluation.assertAvailable(options.requiredRuleIds ?? []);
     await assertSingleTypeUniverse(root, options.signal);
-    const project = await discoverProject(root, policy, options.signal);
+    const project = await discoverProject(root, policy, options.signal, configured.ignore);
     const evaluated = await evaluation.evaluate(project, options.signal);
     const suppression = applySuppressions(collectSuppressionDirectives(project), evaluated.diagnostics);
     const diagnostics = sortDiagnostics(suppression.diagnostics);
-    return {
+    const result = {
         root: project.root,
         policyDigest: policy.digest,
         sourceSnapshotDigest: project.sourceSnapshotDigest,
@@ -41,6 +41,7 @@ async function lintAstraleDomain(options) {
             ? 1
             : 0,
     };
+    return { result, ignorePatterns: configured.ignore.patterns };
 }
 function ensureActive(signal) {
     if (signal?.aborted) {
@@ -52,10 +53,10 @@ function ensureActive(signal) {
 }
 export async function lintDomain(options = {}) {
     const started = performance.now();
-    const domain = await lintAstraleDomain(options);
+    const { result: domain, ignorePatterns } = await lintAstraleDomain(options);
     if (options.generic === false)
         return domain;
-    const generic = await runOxlint(domain.root, options.fix ?? false, { signal: options.signal });
+    const generic = await runOxlint(domain.root, options.fix ?? false, { signal: options.signal }, ignorePatterns);
     const diagnostics = sortDiagnostics([...domain.diagnostics, ...generic.diagnostics]);
     return {
         ...domain,

package/dist/tooling/linter/oxlint/run.d.ts

@@ -4,4 +4,4 @@ export interface OxlintResult {
     readonly diagnostics: readonly LintDiagnostic[];
     readonly files: number;
 }
-export declare function runOxlint(root: string, fix: boolean, options?: OxlintProcessOptions): Promise<OxlintResult>;
+export declare function runOxlint(root: string, fix: boolean, options?: OxlintProcessOptions, projectIgnorePatterns?: readonly string[]): Promise<OxlintResult>;

package/dist/tooling/linter/oxlint/run.js

@@ -7,7 +7,7 @@ import { DOMAIN_OXLINT_IGNORE_PATTERNS } from '../oxlint-config/index.js';
 import { runOxlintProcess } from './process.js';
 const MAX_DIAGNOSTICS = 100_000;
 const MAX_LABELS = 256;
-export async function runOxlint(root, fix, options = {}) {
+export async function runOxlint(root, fix, options = {}, projectIgnorePatterns = []) {
     const packageJson = join(root, 'package.json');
     const projectRequire = createRequire(packageJson);
     const sdkRequire = createRequire(import.meta.url);
@@ -20,6 +20,10 @@ export async function runOxlint(root, fix, options = {}) {
     // fallback config and imported presets cannot discover dependency/build trees.
     for (const pattern of DOMAIN_OXLINT_IGNORE_PATTERNS)
         args.push('--ignore-pattern', pattern);
+    // Domain `ignore` globs are root-relative; the leading slash anchors them the
+    // same way under Oxlint's gitignore semantics.
+    for (const pattern of projectIgnorePatterns)
+        args.push('--ignore-pattern', `/${pattern}`);
     if (fix)
         args.push('--fix');
     const { status, signal, stdout, stderr } = await runOxlintProcess(bin, args, root, options);

package/dist/tooling/linter/policy/configuration.d.ts

@@ -1,4 +1,5 @@
 import type { DomainPolicy, DomainPolicySource } from './index.js';
+import { type DomainLintIgnore } from './ignore.js';
 export declare const DOMAIN_LINT_CONFIG = "astrale.lint.json";
 export interface DomainLintLayerConfiguration {
     readonly sourcePath?: string;
@@ -7,6 +8,7 @@ export interface DomainLintLayerConfiguration {
 export interface DomainLintConfiguration {
     readonly layers?: Readonly<Record<string, DomainLintLayerConfiguration>>;
     readonly disabledRules?: Readonly<Record<string, string>>;
+    readonly ignore?: readonly string[];
 }
 export interface DisabledRule {
     readonly ruleId: string;
@@ -15,6 +17,7 @@ export interface DisabledRule {
 export interface ProjectDomainLint {
     readonly policy: DomainPolicy;
     readonly disabled: readonly DisabledRule[];
+    readonly ignore: DomainLintIgnore;
 }
 export declare function compileProjectDomainPolicy(root: string, signal?: AbortSignal): Promise<DomainPolicy>;
 export declare function compileProjectDomainLint(root: string, signal?: AbortSignal): Promise<ProjectDomainLint>;

package/dist/tooling/linter/policy/configuration.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { LinterToolError } from '../diagnostics/index.js';
 import { compileDomainPolicy } from './compile.js';
 import { domainPolicySource } from './generated.js';
+import { admitIgnorePatterns } from './ignore.js';
 export const DOMAIN_LINT_CONFIG = 'astrale.lint.json';
 const MAX_CONFIG_BYTES = 64 * 1024;
 const MAX_REASON_BYTES = 240;
@@ -17,6 +18,7 @@ export async function compileProjectDomainLint(root, signal) {
     return Object.freeze({
         policy,
         disabled: admitDisabledRules(policy, configuration.disabledRules ?? {}),
+        ignore: admitIgnorePatterns(policy, configuration.ignore),
     });
 }
 export function configureDomainPolicySource(source, configuration) {
@@ -101,7 +103,7 @@ async function readDomainLintConfiguration(root, signal) {
     }
     if (!record(value))
         invalid('Domain lint configuration must be an object.');
-    const unknown = Object.keys(value).filter((field) => field !== 'layers' && field !== 'disabledRules');
+    const unknown = Object.keys(value).filter((field) => field !== 'layers' && field !== 'disabledRules' && field !== 'ignore');
     if (unknown.length > 0) {
         invalid(`Domain lint configuration has unknown fields: ${unknown.join(', ')}.`);
     }

package/dist/tooling/linter/policy/ignore.d.ts

@@ -0,0 +1,11 @@
+import type { DomainPolicy } from './index.js';
+/**
+ * Project-relative paths excluded from Domain source admission. A matched directory is never
+ * traversed, so nothing below it is read, parsed, counted, or digested.
+ */
+export interface DomainLintIgnore {
+    readonly patterns: readonly string[];
+    matches(path: string): boolean;
+}
+export declare const noDomainLintIgnore: DomainLintIgnore;
+export declare function admitIgnorePatterns(policy: DomainPolicy, input: unknown): DomainLintIgnore;

package/dist/tooling/linter/policy/ignore.js

@@ -0,0 +1,101 @@
+import { LinterToolError } from '../diagnostics/index.js';
+const MAX_PATTERNS = 64;
+const MAX_PATTERN_LENGTH = 512;
+const UNSUPPORTED = /[\\[\]{}!]/;
+export const noDomainLintIgnore = Object.freeze({
+    patterns: Object.freeze([]),
+    matches: () => false,
+});
+export function admitIgnorePatterns(policy, input) {
+    if (input === undefined)
+        return noDomainLintIgnore;
+    if (!Array.isArray(input))
+        invalid('Domain lint configuration ignore must be an array.');
+    if (input.length > MAX_PATTERNS) {
+        invalid(`Domain lint configuration ignore has more than ${MAX_PATTERNS} patterns.`);
+    }
+    const governed = new Map([
+        ...policy.layers.map(({ id, sourcePath }) => [
+            sourcePath.replace(/\/$/, ''),
+            `declared layer ${id} (${sourcePath})`,
+        ]),
+        ...policy.rootFiles.map(({ sourcePath }) => [
+            sourcePath,
+            `governed root file ${sourcePath}`,
+        ]),
+    ]);
+    const patterns = [];
+    const expressions = [];
+    for (const value of input) {
+        if (typeof value !== 'string')
+            invalid('Domain lint ignore patterns must be strings.');
+        const segments = segmentsOf(value);
+        const owner = governed.get(segments[0]);
+        if (owner) {
+            invalid(`Domain lint ignore pattern ${JSON.stringify(value)} would exclude ${owner}; ignore only paths outside the Domain layout.`);
+        }
+        if (!patterns.includes(value)) {
+            patterns.push(value);
+            expressions.push(compile(segments));
+        }
+    }
+    if (patterns.length === 0)
+        return noDomainLintIgnore;
+    return Object.freeze({
+        patterns: Object.freeze(patterns),
+        matches: (path) => {
+            // A matched directory excludes everything below it.
+            const segments = path.split('/');
+            return segments.some((_, index) => {
+                const prefix = segments.slice(0, index + 1).join('/');
+                return expressions.some((expression) => expression.test(prefix));
+            });
+        },
+    });
+}
+function segmentsOf(pattern) {
+    const reject = (reason) => invalid(`Domain lint ignore pattern ${JSON.stringify(pattern)} ${reason}.`);
+    if (pattern.length === 0 || pattern.length > MAX_PATTERN_LENGTH) {
+        reject(`must contain 1-${MAX_PATTERN_LENGTH} characters`);
+    }
+    if (pattern.trim() !== pattern)
+        reject('must not start or end with whitespace');
+    if (pattern.startsWith('/'))
+        reject('must be relative to the Domain root');
+    if (UNSUPPORTED.test(pattern))
+        reject("may only use '*', '**', and '?' wildcards");
+    const segments = pattern.replace(/\/$/, '').split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        reject("must not contain empty, '.', or '..' segments");
+    }
+    if (segments.some((segment) => segment.includes('**') && segment !== '**')) {
+        reject("must use '**' as a whole path segment");
+    }
+    if (/[*?]/.test(segments[0])) {
+        reject('must start with a literal root entry, such as mockups/**');
+    }
+    return segments;
+}
+/** `*` and `?` stay within one segment; `**` spans zero or more segments. */
+function compile(segments) {
+    let source = '';
+    for (const [index, segment] of segments.entries()) {
+        if (segment === '**') {
+            source += '(?:/[^/]+)*';
+            continue;
+        }
+        const literal = segment
+            .split('')
+            .map((character) => character === '*'
+            ? '[^/]*'
+            : character === '?'
+                ? '[^/]'
+                : character.replace(/[|\\{}()[\]^$+.]/g, '\\$&'))
+            .join('');
+        source += index === 0 ? literal : `/${literal}`;
+    }
+    return new RegExp(`^${source}$`);
+}
+function invalid(message) {
+    throw new LinterToolError(message, { code: 'LINTER_PROJECT_INVALID' });
+}

package/dist/tooling/linter/policy/index.d.ts

@@ -1,6 +1,7 @@
 export { compileDomainPolicy } from './compile.js';
 export { compileProjectDomainLint, compileProjectDomainPolicy, configureDomainPolicySource, DOMAIN_LINT_CONFIG, } from './configuration.js';
 export { domainPolicyDigest, domainPolicySource } from './generated.js';
+export type { DomainLintIgnore } from './ignore.js';
 import type { RuleCatalog } from '../catalog/index.js';
 export type { DisabledRule, DomainLintConfiguration, DomainLintLayerConfiguration, ProjectDomainLint, } from './configuration.js';
 export interface DomainLayerPolicy {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.6.0-beta.1",
+  "version": "0.6.0-beta.3",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -237,11 +237,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/kernel-client": "0.6.0-beta.71",
-    "@astrale-os/kernel-core": "0.9.0-beta.54",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.39",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.60",
-    "@astrale-os/kernel-server": "0.5.0-beta.62",
+    "@astrale-os/kernel-client": "0.6.0-beta.77",
+    "@astrale-os/kernel-core": "0.9.0-beta.57",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.41",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.63",
+    "@astrale-os/kernel-server": "0.5.0-beta.65",
     "@lucide/icons": "1.34.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "cross-spawn": "7.0.6",