nervur 0.7.6 → 0.8.1

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/being.mjs

@@ -39,6 +39,17 @@ const Compartment = ({ memory, voice, address, root, classOf }) => {
   });
 };
 
+const offered = (modules, program, mine) =>
+  Object.freeze({
+    ...Object.fromEntries(
+      (program?.modules ?? [])
+        .map((one) => one.module)
+        .filter((name) => name !== 'memory' && modules[name] !== undefined)
+        .map((name) => [name, modules[name]]),
+    ),
+    memory: scoped(mine, program),
+  });
+
 const grantable = (program) =>
   (program?.rights ?? [...STRUCTURAL, 'MEMBER']).filter((one) => !STRUCTURAL.includes(one));
 
@@ -240,7 +251,8 @@ const Being = ({ voice, address, deliver, modules, registry, vouched, watch }) =
         }
         const asked = await program.ask({
           context: {
-            modules: Object.freeze({ ...modules, memory: scoped(mine, program) }),
+            from: program.caller ? from : undefined,
+            modules: offered(modules, program, mine),
             port: Port({ voice, mine, deliver, rights }),
             registry,
             rights,

package/blueprint.mjs

@@ -156,6 +156,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) {
@@ -247,6 +308,7 @@ const Blueprint = (source) => {
           resolvers: resolverSources(written.resolvers ?? {}),
         }),
       ),
+      caller: needs.caller === true,
       memory: Object.freeze(memory),
       modules,
       name: written.name,
@@ -278,4 +340,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 { 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';
@@ -41,7 +41,11 @@ const Ground = (modules = {}) => {
     return undefined;
   }
 
-  const program = modules.blueprints?.ground() ?? ADMIN;
+  const extension = modules.blueprints?.ground();
+  const program = extension === undefined ? ADMIN : composed(ADMIN, extension);
+  if (program === undefined || Blueprint(program)?.digest === undefined) {
+    return undefined;
+  }
   if (cells.peek('ground/admin') === undefined) {
     install({ cells, keychain, program });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.7.6",
+  "version": "0.8.1",
   "description": "A distributed system of sovereign beings — one door, one question: by whose authority.",
   "license": "Apache-2.0",
   "author": "Razvan Gherghina",

package/program.mjs

@@ -52,6 +52,7 @@ const Program = (source) => {
       return answered.errors === undefined ? { data: answered.data } : undefined;
     },
     bindings: blueprint.bindings,
+    caller: blueprint.caller,
     classOf: blueprint.classOf,
     config: blueprint.config,
     declares: blueprint.declares,