nervur 0.8.0 → 0.8.2

package/README.md

@@ -313,6 +313,62 @@ MEMBER — once, and never again. `Clock` and `Entropy` are not floor: they
 are ordinary modules a program declares, pinnable so a program never
 reaches for the wall.
 
+## Extending the administration
+
+A ground's administration is a being like any other, and the only one whose
+context holds the registry — so a door that must create, upgrade or destroy
+beings belongs on it and nowhere else. Adopters extend it; nobody replaces
+it.
+
+Pass an extension through the `blueprints` module and the ground composes it
+with the standard administration. Write it as an ordinary blueprint whose
+schema **extends** the roots:
+
+```js
+const cases = `({
+  name: 'procese.cases',
+  needs: { caller: true, modules: [{ module: 'memory', contract: 'nervur.memory' }] },
+  memory: { 'case/*': { type: 'String', class: 'data' } },
+  interface: \`
+    extend type Mutation {
+      openCase(title: String!): String @rights(is: [SELF, MEMBER])
+    }
+  \`,
+  resolvers: {
+    Mutation: {
+      openCase: (_, { title }, { from, modules, registry }) => {
+        const at = registry.create({ program: CASE, refs: [{ address: from }] });
+        modules.memory.write('case/' + at, title);
+        return at ?? null;
+      },
+    },
+  },
+})`;
+
+const ground = Ground({ cells, keychain, blueprints: { ground: () => cases } });
+```
+
+The composed program is one blueprint with one digest, so `describe` answers
+what this ground's administration actually is, and an outsider can pin it.
+
+Three rules hold, and each refuses the whole ground rather than bending:
+
+1. **Standard door names are reserved.** Declare `create`, `census`,
+   `upgrade`, `destroy`, `alias`, `attest`, `opened` or `init` and no ground
+   rises. You cannot change what a standard door means — which is why a
+   stranger may trust that if `create` answers, it created.
+2. **Add only.** Use `extend type Query` / `extend type Mutation`; cell
+   names, module slots and `needs.config` may not collide with the
+   administration's own.
+3. **Close a door the way anything is closed here** — fence it behind a
+   right the ground never grants. The door stands, means what the
+   constitution says, and answers nobody: that is how an appliance ground
+   stops creating beings, without redefining a thing.
+
+The acts stay the core's own: an extension reaches them through the same
+registry face the standard doors use, so it can invent no power the standard
+administration lacked.
+
 ## Writing a module
 
 Five rules, each load-bearing:

package/blueprint.mjs

@@ -80,6 +80,9 @@ const RESERVED = ['eval', 'import', '__proto__', 'prototype', 'Math.random'];
 
 const SHADOWED = FORBIDDEN.map(([name]) => name).filter((name) => !RESERVED.includes(name));
 
+const doorHolder = (one) =>
+  one.kind === Kind.OBJECT_TYPE_DEFINITION || one.kind === Kind.OBJECT_TYPE_EXTENSION;
+
 const RIGHTS_DIRECTIVE = 'directive @rights(is: [Rights!]!) on FIELD_DEFINITION';
 
 const DEFAULT_RIGHTS = `enum Rights { SELF MEMBER STRANGER }`;
@@ -156,6 +159,67 @@ const resolverSources = (resolvers) =>
         .map((field) => `${type}.${field}=${resolvers[type][field].toString()}`),
     );
 
+const merged = (base, added) =>
+  Object.fromEntries(
+    [...new Set([...Object.keys(base ?? {}), ...Object.keys(added ?? {})])].map((key) => [
+      key,
+      { ...(base ?? {})[key], ...(added ?? {})[key] },
+    ]),
+  );
+
+const doorsIn = (sdl) =>
+  parse(sdl)
+    .definitions.filter(
+      (one) => one.kind === Kind.OBJECT_TYPE_DEFINITION || one.kind === Kind.OBJECT_TYPE_EXTENSION,
+    )
+    .flatMap((one) => (one.fields ?? []).map((field) => `${one.name.value}.${field.name.value}`));
+
+const composed = (baseSource, addedSource) => {
+  try {
+    const base = evaluated(baseSource);
+    const added = evaluated(addedSource);
+    const standard = doorsIn(base.interface);
+    if (doorsIn(added.interface).some((one) => standard.includes(one))) {
+      return undefined;
+    }
+    const cells = { ...(base.memory ?? {}), ...(added.memory ?? {}) };
+    if (
+      Object.keys(base.memory ?? {}).some((key) => (added.memory ?? {})[key] !== undefined) ||
+      (added.needs?.config !== undefined && base.needs?.config !== undefined)
+    ) {
+      return undefined;
+    }
+    const slots = [...(base.needs?.modules ?? []), ...(added.needs?.modules ?? [])];
+    if (new Set(slots.map((one) => one.module)).size !== slots.length) {
+      return undefined;
+    }
+    const needs = {
+      ...(base.needs ?? {}),
+      ...(added.needs ?? {}),
+      caller: base.needs?.caller === true || added.needs?.caller === true,
+      modules: slots,
+    };
+    const doors = merged(base.resolvers, added.resolvers);
+    const written = Object.entries(doors)
+      .map(
+        ([type, fields]) =>
+          `${type}: { ${Object.entries(fields)
+            .map(([field, one]) => `${field}: ${one.toString()}`)
+            .join(', ')} }`,
+      )
+      .join(', ');
+    return `({
+  name: ${JSON.stringify(added.name)},
+  needs: ${JSON.stringify(needs)},
+  memory: ${JSON.stringify(cells)},
+  interface: ${JSON.stringify(`${base.interface}\n${added.interface}`)},
+  resolvers: { ${written} },
+})`;
+  } catch {
+    return undefined;
+  }
+};
+
 const inputCheck = (schema, typeName, given) => {
   const type = schema.getType(typeName);
   if (type?.getFields === undefined) {
@@ -189,10 +253,10 @@ const Blueprint = (source) => {
     ];
 
     const admits = (typeName, fieldName, held) => {
-      const type = document.definitions.find(
-        (one) => one.kind === Kind.OBJECT_TYPE_DEFINITION && one.name.value === typeName,
-      );
-      const field = type?.fields?.find((one) => one.name.value === fieldName);
+      const field = document.definitions
+        .filter((one) => doorHolder(one) && one.name.value === typeName)
+        .flatMap((one) => one.fields ?? [])
+        .find((one) => one.name.value === fieldName);
       const allowed = field === undefined ? undefined : rightsOf(field);
       return allowed === undefined ? true : allowed.includes(held);
     };
@@ -212,7 +276,7 @@ const Blueprint = (source) => {
       schema.getSubscriptionType()?.name,
     ].filter((one) => one !== undefined);
     const undeclared = document.definitions
-      .filter((one) => one.kind === Kind.OBJECT_TYPE_DEFINITION && roots.includes(one.name.value))
+      .filter((one) => doorHolder(one) && roots.includes(one.name.value))
       .flatMap((one) => one.fields ?? [])
       .filter((one) => {
         const allowed = rightsOf(one);
@@ -260,17 +324,17 @@ const Blueprint = (source) => {
           ...document,
           definitions: document.definitions
             .map((one) =>
-              one.kind === Kind.OBJECT_TYPE_DEFINITION
+              doorHolder(one)
                 ? {
                     ...one,
-                    fields: one.fields.filter((field) => {
+                    fields: (one.fields ?? []).filter((field) => {
                       const allowed = rightsOf(field);
                       return allowed === undefined || allowed.includes(held);
                     }),
                   }
                 : one,
             )
-            .filter((one) => one.kind !== Kind.OBJECT_TYPE_DEFINITION || one.fields.length > 0),
+            .filter((one) => !doorHolder(one) || one.fields.length > 0),
         }),
       trespass: [],
     });
@@ -279,4 +343,4 @@ const Blueprint = (source) => {
   }
 };
 
-export { Blueprint, CLASSES, CORE_ONLY, FORBIDDEN, OPEN, STRUCTURAL, coreClass, reads };
+export { Blueprint, CLASSES, CORE_ONLY, FORBIDDEN, OPEN, STRUCTURAL, composed, coreClass, reads };

package/ground.mjs

@@ -1,6 +1,6 @@
 import { ADMIN } from './admin.mjs';
 import { Being, Compartment, Registry, make, rootFor } from './being.mjs';
-import { Blueprint, coreClass } from './blueprint.mjs';
+import { Blueprint, composed, coreClass } from './blueprint.mjs';
 import { Client } from './client.mjs';
 import { Contracts } from './contract.mjs';
 import { Memory, Paths, Wire } from './modules.mjs';
@@ -13,22 +13,6 @@ const GROUND = 'Ground';
 
 const FLOOR = ['blueprints', 'cells', 'contracts', 'keychain', 'paths', 'watch', 'wire'];
 
-const doorsOf = (source) => {
-  const written = Blueprint(source);
-  if (written === undefined) {
-    return undefined;
-  }
-  return [written.schema.getQueryType(), written.schema.getMutationType()]
-    .filter((one) => one !== undefined && one !== null)
-    .flatMap((one) => Object.keys(one.getFields()));
-};
-
-const redefines = (source) => {
-  const custom = doorsOf(source);
-  const standard = doorsOf(ADMIN);
-  return custom === undefined || custom.some((one) => standard.includes(one));
-};
-
 const install = ({ cells, keychain, program }) => {
   const memory = Memory(cells);
   const voice = Voice();
@@ -58,10 +42,10 @@ const Ground = (modules = {}) => {
   }
 
   const extension = modules.blueprints?.ground();
-  if (extension !== undefined && redefines(extension)) {
+  const program = extension === undefined ? ADMIN : composed(ADMIN, extension);
+  if (program === undefined || Blueprint(program)?.digest === undefined) {
     return undefined;
   }
-  const program = extension ?? ADMIN;
   if (cells.peek('ground/admin') === undefined) {
     install({ cells, keychain, program });
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nervur",
-  "version": "0.8.0",
-  "description": "A distributed system of sovereign beings — one door, one question: by whose authority.",
+  "version": "0.8.2",
+  "description": "A distributed system of sovereign beings \u2014 one door, one question: by whose authority.",
   "license": "Apache-2.0",
   "author": "Razvan Gherghina",
   "homepage": "https://nervur.org",