@astrale-domains/shell 0.1.0-beta.46 → 0.1.0-beta.49

package/README.md

@@ -1,7 +1,8 @@
 # Shell Domain
 
 Shell owns two concrete Identity classes, User and Group, the member_of_group relation,
-the admin/member/applications Core groups, three static methods, one Domain function, and one
+the admin/member/applications Core groups, the Namespace class and its alias relation, the `views`
+Core Namespace, three static methods, three Namespace methods, one Domain function, and one
 application View, which is its entrypoint. The Schema names the Domain `Shell`. There is no Space, setup function, personal home, or public repair method.
 
 ## Contracts
@@ -12,6 +13,12 @@ application View, which is its entrypoint. The Schema names the Domain `Shell`.
 | Group.assignMember | `{ member: UserPath \| GroupPath, group: GroupPath }` | `{}` |
 | Group.unassignMember | Same | `{}` |
 
+| Namespace method | Input | Output |
+| --- | --- | --- |
+| Namespace.link | `{ name: string, target: NodePath }` | `{}` |
+| Namespace.unlink | `{ name: string }` | `{}` |
+| Namespace.rename | `{ name: string, to: string }` | `{}` |
+
 | Domain function | Input | Output |
 | --- | --- | --- |
 | listEntrypoints | `{}` | `{ entrypoints: { origin, name, view }[] }` |
@@ -27,7 +34,9 @@ The workspace opens only once listEntrypoints answers, so every profile that adm
 the workspace holds it. Administrators and members hold both listEntrypoints and View.resolve
 directly (a Core Edge cannot author Kernel `extends_with`): an invited person, whom Admin assigns
 to Core member, can open the workspace. The Core `applications` Group carries the same two
-capabilities for Identities outside Members. Share them dynamically with
+capabilities for Identities outside Members, and `query`: the `/v/<name>` page reads its Path with
+a Query under the visitor's own rights, so read rules still decide what it sees. Share them
+dynamically with
 `Group.assignMember({ member: identity, group: applications })`, which composes the profile through
 `extends_with`; `unassignMember` withdraws it.
 
@@ -52,6 +61,48 @@ With Kernel Host beta94 or newer, an external caller needs callable authority th
 identity composition AND a passing callable Policy. Declare exact foreign methods in the calling
 Domain's requirements; can_use no longer bypasses the Policy. Root and exact owner exceptions remain.
 
+## Namespaces and aliases
+
+**An alias names a Node. It grants nothing.** A name designates at most one Node in its
+Namespace, for every author: `alias` declares the Kernel key `unique: [['source', 'slug']]` in its
+first release, so the Kernel refuses a taken name on the final state of any Mutation, Shell's or an
+administrator's own `mutate`. Edge identity gives a Node at most one alias per Namespace. An alias
+is a Path, `/:shell.astrale.ai:core.views~"shell.astrale.ai:class.alias"(roadmap)`, and reaches its
+Node only for a reader who may read that Node. Its target endpoint accepts any Node, a Class Shell
+does not own, so the alias detaches when its Node is deleted; the Namespace stays.
+
+The Core Namespace `views` holds the names opened at `/v/<name>`. Namespace and alias declare
+`read: true` and `traverse: true`: a reader lists and follows the aliases whose Node it may read,
+and an alias toward any other Node does not exist for it. Shell, through its own alias Edges,
+finds the Node of every name, even one it does not read.
+
+`link` names any Node its target Path reaches, whatever Domain owns it: an alias grants nothing,
+and each reader sees only the aliases toward Nodes it may read. Offering only Nodes the
+administrator sees is the interface's courtesy, not a server guarantee; any writer already learns
+from a Mutation's locator whether a Path reaches a Node.
+
+| Method | Calls | Refusals |
+| --- | --- | --- |
+| link | One Mutation with Shell's authority; its locator resolves `target` | `INVALID_NAME`, `TARGET_NOT_FOUND`, `NAME_TAKEN`, `TARGET_ALREADY_ALIASED` |
+| unlink | One read of the alias Path with Shell's authority, then one Mutation | `INVALID_NAME`, `NAME_NOT_FOUND` |
+| rename | Same; renaming a name to itself writes nothing | `INVALID_NAME`, `NAME_NOT_FOUND`, `NAME_TAKEN` |
+
+A name is an Edge slug in lower case (`INVALID_NAME`). That rule is Shell's: an administrator
+writing through `mutate` bypasses it, never the key. Nothing guards a name's uniqueness but the key.
+`unlink` and `rename` change the alias only while it still carries the name they read, so a
+concurrent rename answers `NAME_NOT_FOUND` instead of changing another name. Shell maps the Kernel's
+sealed refusals:
+
+| Kernel refusal of the Mutation | link | unlink | rename |
+| --- | --- | --- | --- |
+| `MUTATION_POST_STATE_INVALID`, rule `duplicate-key` | `NAME_TAKEN` | propagates | `NAME_TAKEN` |
+| `MUTATION_PRECONDITION_FAILED` (the alias Edge exists, is gone, or carries another name) | `TARGET_ALREADY_ALIASED` | `NAME_NOT_FOUND` | `NAME_NOT_FOUND` |
+| `MUTATION_LOCATOR_INVALID` (the target Path reaches no Node, or the target was deleted) | `TARGET_NOT_FOUND` | `NAME_NOT_FOUND` | `NAME_NOT_FOUND` |
+
+Every other failure propagates. Core admin holds the three methods, `read` and `traverse` on
+Namespace, and every operation on alias. Administration follows `administersShellClass` on the
+Namespace, as for Groups.
+
 ## Flows
 
 ```text
@@ -91,9 +142,10 @@ Kernel E2E evidence, not a handler test, qualifies this behavior.
 
 The Shell principal requests all Kernel root functions, the required extends_with operations,
 and the declared grant/revoke authority. Core admin receives the full declared Shell profile,
-including invite, assignMember and unassignMember so humans inheriting admin can call those methods.
-Core member receives Download, Introspect, Query, Mutate, View.resolve and listEntrypoints, not
-blanket class-read grants.
+including invite, assignMember, unassignMember, link, unlink and rename so humans inheriting admin
+can call those methods. Core member receives Download, Introspect, Query, Mutate, View.resolve and
+listEntrypoints, not blanket class-read grants. Core applications receives listEntrypoints,
+View.resolve and Query.
 The Domain definition's requirements, including Core Identity capabilities in requirements.core, are owned by domain.ts and materialized by installation,
 never by invitation handlers.
 

package/dist/domain.d.ts

@@ -7,6 +7,7 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
     readonly classes: {
         readonly User: import("@astrale-os/sdk/schema").AuthoredNodeClass<{
             readonly icon: import("@astrale-os/sdk/schema").ClassIcon;
+            readonly inheritance: "open";
             readonly policies: {
                 readonly read: true;
             };
@@ -30,6 +31,7 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
         }>;
         readonly Group: import("@astrale-os/sdk/schema").AuthoredNodeClass<{
             readonly icon: import("@astrale-os/sdk/schema").ClassIcon;
+            readonly inheritance: "open";
             readonly policies: {
                 readonly read: true;
             };
@@ -67,6 +69,52 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
             readonly constraints: Record<never, never>;
             readonly effectiveProperties: never;
         }>;
+        readonly Namespace: import("@astrale-os/sdk/schema").AuthoredNodeClass<{
+            readonly icon: import("@astrale-os/sdk/schema").ClassIcon;
+            readonly policies: {
+                readonly read: true;
+                readonly traverse: true;
+            };
+            readonly extends: readonly [import("@astrale-os/sdk/schema").KernelClass<"Named">, import("@astrale-os/sdk/schema").KernelClass<"Descriptable">];
+            readonly methods: {
+                readonly link: import("@astrale-os/sdk/schema").Method<import("@astrale-os/sdk/schema").CallableProjection<{
+                    name: string;
+                    target: string;
+                }, {
+                    readonly mode: 'value';
+                    readonly value: Record<string, never>;
+                }, "authorized", false, false, undefined, undefined>>;
+                readonly unlink: import("@astrale-os/sdk/schema").Method<import("@astrale-os/sdk/schema").CallableProjection<{
+                    name: string;
+                }, {
+                    readonly mode: 'value';
+                    readonly value: Record<string, never>;
+                }, "authorized", false, false, undefined, undefined>>;
+                readonly rename: import("@astrale-os/sdk/schema").Method<import("@astrale-os/sdk/schema").CallableProjection<{
+                    name: string;
+                    to: string;
+                }, {
+                    readonly mode: 'value';
+                    readonly value: Record<string, never>;
+                }, "authorized", false, false, undefined, undefined>>;
+            };
+        }>;
+        readonly alias: import("@astrale-os/sdk/schema").DirectedEdgeClass<{
+            readonly depth: 0;
+            readonly abstract: false;
+            readonly extends: readonly [];
+            readonly properties: never;
+            readonly source: {
+                readonly as: "namespace";
+                readonly outgoing: "0..*";
+            };
+            readonly target: {
+                readonly as: "node";
+                readonly incoming: "0..*";
+            };
+            readonly constraints: Record<never, never>;
+            readonly effectiveProperties: never;
+        }>;
     };
     readonly functions: {
         readonly listEntrypoints: import("@astrale-os/sdk/schema").Function<import("@astrale-os/sdk/schema").CallableProjection<Record<string, never>, {
@@ -94,6 +142,7 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
             readonly admin: import("@astrale-os/sdk/schema").CoreNode;
             readonly applications: import("@astrale-os/sdk/schema").CoreNode;
             readonly member: import("@astrale-os/sdk/schema").CoreNode;
+            readonly views: import("@astrale-os/sdk/schema").CoreNode;
         };
     };
 }, {

package/dist/domain.js

@@ -31,6 +31,9 @@ const domainRequirements = requirements({
                 S.classes.User.static.methods.invite,
                 S.classes.Group.static.methods.assignMember,
                 S.classes.Group.static.methods.unassignMember,
+                S.classes.Namespace.methods.link,
+                S.classes.Namespace.methods.unlink,
+                S.classes.Namespace.methods.rename,
                 // Core Edges cannot author Kernel extends_with, so administrators hold it directly.
                 S.functions.listEntrypoints,
             ],
@@ -44,6 +47,8 @@ const domainRequirements = requirements({
                     class: S.classes.member_of_group,
                     operations: ['create', 'read', 'traverse', 'update', 'delete'],
                 },
+                { class: S.classes.Namespace, operations: ['read', 'traverse'] },
+                { class: S.classes.alias, operations: ['create', 'read', 'traverse', 'update', 'delete'] },
                 { class: K.classes.extends_with, operations: ['create', 'read', 'traverse', 'delete'] },
             ],
             authority: {
@@ -66,8 +71,14 @@ const domainRequirements = requirements({
         },
         {
             // For Identities outside Members: Group.assignMember(identity, applications) composes it.
+            // `query` opens `/v/<name>`: the full page reads that Path with a Query under the visitor's
+            // own rights, so read rules still decide what it sees.
             subject: S.core.nodes.applications,
-            functions: [S.functions.listEntrypoints, K.classes.View.static.methods.resolve],
+            functions: [
+                S.functions.listEntrypoints,
+                K.classes.View.static.methods.resolve,
+                K.functions.query,
+            ],
         },
     ],
 });

package/dist/functions/namespace/index.js

@@ -0,0 +1,3 @@
+export { link } from './link.js';
+export { unlink } from './unlink.js';
+export { rename } from './rename.js';

package/dist/functions/namespace/link.js

@@ -0,0 +1,30 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { Path } from '@astrale-os/sdk/graph/path';
+import { linkAlias } from '../../mutations/namespace/index.js';
+import { namespaceErrors } from './namespace-errors.js';
+import { namespaceSlug } from './namespace-name.js';
+/**
+ * One Mutation with Shell's own authority. An alias grants nothing and each reader sees only the
+ * aliases toward Nodes it may read, so `link` names any Node its target Path reaches; the `alias`
+ * key keeps a name to one Node for every author.
+ */
+export const link = defineAction()('Namespace.link', { errors: namespaceErrors }, async ({ error, mutate, input, self }) => {
+    const name = namespaceSlug(input.name);
+    if (name === undefined)
+        throw error('INVALID_NAME', { name: input.name });
+    const result = await mutate(linkAlias, {
+        namespace: self,
+        name,
+        target: Path.parse(input.target),
+    });
+    if (result.ok)
+        return {};
+    switch (result.refusal) {
+        case 'NAME_TAKEN':
+            throw error('NAME_TAKEN', { name });
+        case 'TARGET_ALREADY_ALIASED':
+            throw error('TARGET_ALREADY_ALIASED', {});
+        case 'TARGET_NOT_FOUND':
+            throw error('TARGET_NOT_FOUND', {});
+    }
+});

package/dist/functions/namespace/namespace-errors.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export const namespaceErrors = {
+    INVALID_NAME: {
+        family: 'VALIDATION_ERROR',
+        message: 'A name uses lower-case letters, digits, ".", "_" and "-", and starts and ends with a letter or digit.',
+        details: z.strictObject({ name: z.string() }),
+    },
+    TARGET_NOT_FOUND: {
+        family: 'NOT_FOUND',
+        message: 'The target Path reaches no Node.',
+        details: z.strictObject({}),
+    },
+    NAME_TAKEN: {
+        family: 'CONFLICT',
+        message: 'This name already designates a Node in this Namespace.',
+        details: z.strictObject({ name: z.string() }),
+    },
+    TARGET_ALREADY_ALIASED: {
+        family: 'CONFLICT',
+        message: 'This Node already has an alias in this Namespace; rename it instead.',
+        details: z.strictObject({}),
+    },
+    NAME_NOT_FOUND: {
+        family: 'NOT_FOUND',
+        message: 'No alias of this Namespace has this name.',
+        details: z.strictObject({ name: z.string() }),
+    },
+};

package/dist/functions/namespace/namespace-name.js

@@ -0,0 +1,13 @@
+import { EdgeSlug, isEdgeSlug } from '@astrale-os/sdk/graph/edge';
+import { Path } from '@astrale-os/sdk/graph/path';
+/** The Edge slug a name is: an exact Edge slug, in lower case. Anything else is no name. */
+export function namespaceSlug(name) {
+    return isEdgeSlug(name) && name === name.toLowerCase() ? EdgeSlug(name) : undefined;
+}
+/**
+ * The Path of one name of a Namespace: `@<namespace>~"<alias>"(<name>)`. The `alias` key comes from
+ * the admitted Domain, so the Worker never loads the Schema's builder.
+ */
+export function aliasPath(domain, namespace, name) {
+    return Path.id(namespace).out(domain.classes.alias.key, { slug: name });
+}

package/dist/functions/namespace/rename.js

@@ -0,0 +1,31 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { renameAlias } from '../../mutations/namespace/index.js';
+import { readDesignatedNode } from '../../queries/namespace/index.js';
+import { namespaceErrors } from './namespace-errors.js';
+import { aliasPath, namespaceSlug } from './namespace-name.js';
+/**
+ * One read of the Node the name designates, then one Mutation renaming its alias while it still
+ * carries that name. Renaming a name to itself finds the Node and writes nothing.
+ */
+export const rename = defineAction()('Namespace.rename', { errors: namespaceErrors }, async ({ domain, error, query, mutate, input, self }) => {
+    const name = namespaceSlug(input.name);
+    if (name === undefined)
+        throw error('INVALID_NAME', { name: input.name });
+    const to = namespaceSlug(input.to);
+    if (to === undefined)
+        throw error('INVALID_NAME', { name: input.to });
+    const target = await query(readDesignatedNode, { path: aliasPath(domain, self, name) });
+    if (target === undefined)
+        throw error('NAME_NOT_FOUND', { name });
+    if (to === name)
+        return {};
+    const result = await mutate(renameAlias, { namespace: self, target, name, to });
+    if (result.ok)
+        return {};
+    switch (result.refusal) {
+        case 'NAME_TAKEN':
+            throw error('NAME_TAKEN', { name: to });
+        case 'NAME_NOT_FOUND':
+            throw error('NAME_NOT_FOUND', { name });
+    }
+});

package/dist/functions/namespace/unlink.js

@@ -0,0 +1,21 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { unlinkAlias } from '../../mutations/namespace/index.js';
+import { readDesignatedNode } from '../../queries/namespace/index.js';
+import { namespaceErrors } from './namespace-errors.js';
+import { aliasPath, namespaceSlug } from './namespace-name.js';
+/**
+ * One read of the Node the name designates, then one Mutation deleting its alias while it still
+ * carries that name: a concurrent rename answers NAME_NOT_FOUND instead of removing another name.
+ */
+export const unlink = defineAction()('Namespace.unlink', { errors: namespaceErrors }, async ({ domain, error, query, mutate, input, self }) => {
+    const name = namespaceSlug(input.name);
+    if (name === undefined)
+        throw error('INVALID_NAME', { name: input.name });
+    const target = await query(readDesignatedNode, { path: aliasPath(domain, self, name) });
+    if (target === undefined)
+        throw error('NAME_NOT_FOUND', { name });
+    const result = await mutate(unlinkAlias, { namespace: self, target, name });
+    if (result.ok)
+        return {};
+    throw error('NAME_NOT_FOUND', { name });
+});

package/dist/index.d.ts

@@ -1 +1 @@
-export { ShellSchema, S, type Shell, type ShellClasses, type ShellSchemaInput, type InvitationSummary, User, Group, member_of_group, adminGroup, memberGroup, } from './schema/index.js';
+export { ShellSchema, S, type Shell, type ShellClasses, type ShellSchemaInput, type InvitationSummary, User, Group, member_of_group, adminGroup, memberGroup, Namespace, alias, viewsNamespace, } from './schema/index.js';

package/dist/index.js

@@ -1 +1 @@
-export { ShellSchema, S, User, Group, member_of_group, adminGroup, memberGroup, } from './schema/index.js';
+export { ShellSchema, S, User, Group, member_of_group, adminGroup, memberGroup, Namespace, alias, viewsNamespace, } from './schema/index.js';

package/dist/mutations/namespace/alias-write.js

@@ -0,0 +1,22 @@
+export const written = Object.freeze({ ok: true });
+/** Turn the Kernel refusals an alias write expects into its Namespace refusal; others propagate. */
+export function rejectAliasWrite(refusals) {
+    return (failure) => {
+        if (failure.outcomeKnown) {
+            if (refusals.name !== undefined &&
+                failure.code === 'MUTATION_POST_STATE_INVALID' &&
+                'rule' in failure &&
+                failure.rule === 'duplicate-key') {
+                return refused(refusals.name);
+            }
+            if (failure.code === 'MUTATION_PRECONDITION_FAILED')
+                return refused(refusals.edge);
+            if (failure.code === 'MUTATION_LOCATOR_INVALID')
+                return refused(refusals.node);
+        }
+        throw failure;
+    };
+}
+function refused(refusal) {
+    return Object.freeze({ ok: false, refusal });
+}

package/dist/mutations/namespace/index.js

@@ -0,0 +1,3 @@
+export { linkAlias } from './link-alias.js';
+export { unlinkAlias } from './unlink-alias.js';
+export { renameAlias } from './rename-alias.js';

package/dist/mutations/namespace/link-alias.js

@@ -0,0 +1,15 @@
+import { defineMutation } from '@astrale-os/sdk/mutation';
+import { rejectAliasWrite, written } from './alias-write.js';
+/** Create the alias `name` from a Namespace to the one Node a Path reaches. */
+export const linkAlias = defineMutation()((domain) => ({
+    id: 'shell.namespace.alias.link',
+    build({ namespace, name, target }, mutation) {
+        mutation.createEdge({ class: domain.classes.alias, source: namespace, target, slug: name });
+    },
+    project: () => written,
+    reject: rejectAliasWrite({
+        name: 'NAME_TAKEN',
+        edge: 'TARGET_ALREADY_ALIASED',
+        node: 'TARGET_NOT_FOUND',
+    }),
+}));

package/dist/mutations/namespace/rename-alias.js

@@ -0,0 +1,13 @@
+import { defineMutation } from '@astrale-os/sdk/mutation';
+import { rejectAliasWrite, written } from './alias-write.js';
+/** Rename the alias `name` of one Node in a Namespace to `to`; the Node it names stays the same. */
+export const renameAlias = defineMutation()((domain) => ({
+    id: 'shell.namespace.alias.rename',
+    build({ namespace, target, name, to }, mutation) {
+        const alias = { class: domain.classes.alias, source: namespace, target };
+        mutation.expect.edge({ ...alias, slug: name });
+        mutation.updateEdge({ ...alias, slug: to });
+    },
+    project: () => written,
+    reject: rejectAliasWrite({ name: 'NAME_TAKEN', edge: 'NAME_NOT_FOUND', node: 'NAME_NOT_FOUND' }),
+}));

package/dist/mutations/namespace/unlink-alias.js

@@ -0,0 +1,13 @@
+import { defineMutation } from '@astrale-os/sdk/mutation';
+import { rejectAliasWrite, written } from './alias-write.js';
+/** Delete the alias `name` of one Node in a Namespace: Edge identity gives the Node at most one. */
+export const unlinkAlias = defineMutation()((domain) => ({
+    id: 'shell.namespace.alias.unlink',
+    build({ namespace, target, name }, mutation) {
+        const alias = { class: domain.classes.alias, source: namespace, target };
+        mutation.expect.edge({ ...alias, slug: name });
+        mutation.deleteEdge(alias);
+    },
+    project: () => written,
+    reject: rejectAliasWrite({ edge: 'NAME_NOT_FOUND', node: 'NAME_NOT_FOUND' }),
+}));

package/dist/queries/namespace/index.js

@@ -0,0 +1 @@
+export { readDesignatedNode } from './read-designated-node.js';

package/dist/queries/namespace/read-designated-node.js

@@ -0,0 +1,12 @@
+import { defineQuery, Query, queryResult } from '@astrale-os/sdk/query';
+/**
+ * The one Node a Path designates for the authority that reads it, or nothing: a Node it cannot
+ * see, and a name no alias holds, read the same.
+ */
+export const readDesignatedNode = defineQuery()(() => ({
+    id: 'shell.namespace.designated-node',
+    page: { size: 1 },
+    pagination: { maximumPages: 1 },
+    build: ({ path }) => Query.from({ nodes: [path] }).select({ kind: 'nodes', projection: { kind: 'reference' } }),
+    project: (pages) => queryResult.completeNodeIds(pages, 'Shell designated Node')[0],
+}));