nervur 0.3.0 → 0.6.0

package/contract.mjs

@@ -0,0 +1,96 @@
+import { buildSchema, isEnumType, isInputObjectType, parse, print } from 'graphql';
+import { Tools } from './tools.mjs';
+
+const argsAgree = (wanted, given) => {
+  for (const arg of wanted.args ?? []) {
+    const same = (given.args ?? []).find((one) => one.name === arg.name);
+    if (same === undefined || String(same.type) !== String(arg.type)) {
+      return false;
+    }
+  }
+  return (given.args ?? [])
+    .filter((one) => !(wanted.args ?? []).some((asked) => asked.name === one.name))
+    .every((one) => !String(one.type).endsWith('!') || one.defaultValue !== undefined);
+};
+
+const Contract = (name, sdl) => {
+  try {
+    const schema = buildSchema(sdl);
+    const printed = print(parse(sdl));
+    return Object.freeze({
+      digest: Tools.digest(Tools.canon({ interface: printed, name })),
+      name,
+      satisfies: (offered) => {
+        const theirs = (() => {
+          try {
+            return buildSchema(offered);
+          } catch {
+            return undefined;
+          }
+        })();
+        if (theirs === undefined) {
+          return false;
+        }
+        for (const [typeName, wanted] of Object.entries(schema.getTypeMap())) {
+          if (typeName.startsWith('__')) {
+            continue;
+          }
+          const given = theirs.getTypeMap()[typeName];
+          if (isEnumType(wanted)) {
+            if (
+              !isEnumType(given) ||
+              !wanted.getValues().every((one) => given.getValue(one.name) !== undefined)
+            ) {
+              return false;
+            }
+            continue;
+          }
+          if (wanted.getFields === undefined) {
+            continue;
+          }
+          if (given?.getFields === undefined) {
+            return false;
+          }
+          for (const [field, held] of Object.entries(wanted.getFields())) {
+            const mine = given.getFields()[field];
+            if (mine === undefined || String(mine.type) !== String(held.type)) {
+              return false;
+            }
+            if (!argsAgree(held, mine)) {
+              return false;
+            }
+          }
+          if (isInputObjectType(wanted)) {
+            const demanded = Object.entries(given.getFields())
+              .filter(([field]) => wanted.getFields()[field] === undefined)
+              .filter(
+                ([, one]) => String(one.type).endsWith('!') && one.defaultValue === undefined,
+              );
+            if (demanded.length > 0) {
+              return false;
+            }
+          }
+        }
+        return true;
+      },
+      sdl: printed,
+    });
+  } catch {
+    return undefined;
+  }
+};
+
+const Contracts = (written) => {
+  const held = Object.entries(written).map(([name, sdl]) => Contract(name, sdl));
+  if (held.some((one) => one === undefined)) {
+    return undefined;
+  }
+  const byName = new Map(held.map((one) => [one.name, one]));
+  return Object.freeze({
+    digests: () => Object.fromEntries(held.map((one) => [one.name, one.digest])),
+    get: (name) => byName.get(name),
+    has: (name) => byName.has(name),
+  });
+};
+
+export { Contract, Contracts };

package/ground.mjs

@@ -0,0 +1,196 @@
+import { ADMIN } from './admin.mjs';
+import { Being, Compartment, Registry, make, rootFor } from './being.mjs';
+import { coreClass } from './blueprint.mjs';
+import { Client } from './client.mjs';
+import { Contracts } from './contract.mjs';
+import { Memory, Paths, Wire } from './modules.mjs';
+import { Mcp, Pointer } from './pointer.mjs';
+import { Program } from './program.mjs';
+import { Stamp, Tools } from './tools.mjs';
+import { Voice } from './voice.mjs';
+
+const GROUND = 'Ground';
+
+const FLOOR = ['blueprints', 'cells', 'contracts', 'keychain', 'paths', 'watch', 'wire'];
+
+const install = ({ cells, keychain, program }) => {
+  const memory = Memory(cells);
+  const voice = Voice();
+  const address = Tools.address(voice.pk);
+  const sealed = keychain.seal(voice.pack());
+  if (sealed === undefined) {
+    return;
+  }
+  make({ memory, voice, address, program });
+  cells.put('ground/admin', { address, sealed });
+};
+
+const Ground = (modules = {}) => {
+  const cells = modules.cells;
+  const keychain = modules.keychain;
+  if (cells === undefined || keychain?.seal === undefined || keychain?.unseal === undefined) {
+    return undefined;
+  }
+
+  const written = modules.contracts ?? Contracts({});
+  const extra = Object.fromEntries(
+    Object.entries(modules).filter(([name]) => !FLOOR.includes(name)),
+  );
+  const bound = Object.entries(extra).filter(([, one]) => one?.at !== undefined);
+  if (bound.some(([, one]) => !written.has(one.contract))) {
+    return undefined;
+  }
+
+  const program = modules.blueprints?.ground() ?? ADMIN;
+  if (cells.peek('ground/admin') === undefined) {
+    install({ cells, keychain, program });
+  }
+  const installed = cells.peek('ground/admin');
+  if (installed === undefined) {
+    return undefined;
+  }
+  const bundle = keychain.unseal(installed.sealed);
+  const adminVoice = bundle === undefined ? undefined : Voice.revive(bundle);
+  if (adminVoice === undefined) {
+    return undefined;
+  }
+
+  // Never leaves this closure — nothing outside may be handed it.
+  const vouched = Symbol('vouched');
+
+  const watch = (fact) => {
+    try {
+      modules.watch?.(Object.freeze(fact));
+    } catch {
+      return undefined;
+    }
+  };
+
+  const address = installed.address;
+  const memory = Memory(cells);
+  const paths = modules.paths ?? Paths(new Map());
+  const wire = modules.wire ?? Wire();
+
+  const stamp = Stamp();
+  const boundFor = (voice) =>
+    Object.fromEntries(
+      bound.map(([name, one]) => [
+        name,
+        Pointer(written.get(one.contract).sdl, (source, variables) =>
+          deliver(Tools.envelope(voice, one.at, { ask: { source, variables } }, stamp())),
+        ),
+      ]),
+    );
+  const modulesFor = (voice) =>
+    Object.freeze({
+      ...extra,
+      ...boundFor(voice),
+      deliver: (envelope) => deliver(envelope),
+      memory,
+      paths,
+      wire,
+    });
+  const adminModules = modulesFor(adminVoice);
+
+  const adminMine = Compartment({
+    memory,
+    voice: adminVoice,
+    address,
+    root: rootFor({ memory, voice: adminVoice, address }),
+    classOf: (key) =>
+      Program(memory.read(address, 'program')?.value)?.classOf(key) ?? coreClass(key),
+  });
+
+  const receive = async (envelope, token) => {
+    const at = envelope?.to;
+    const door = at === address ? admin : registry.activate(at);
+    if (door === undefined) {
+      watch({
+        from: envelope?.from,
+        kind: envelope?.op === undefined ? undefined : Object.keys(envelope.op)[0],
+        outcome: 'no-door',
+        to: at,
+      });
+      return undefined;
+    }
+    return door(envelope, token);
+  };
+  const announce = (at) => paths.publish(at, receive);
+  const forget = (at) => {
+    paths.publish(at, undefined);
+    cells.drop(`${at}/`);
+  };
+
+  const attest = async (name) => {
+    const one = extra[name];
+    if (one?.at === undefined) {
+      return adminModules[name] !== undefined;
+    }
+    const seen = await deliver(Tools.envelope(adminVoice, one.at, { describe: {} }, stamp()));
+    return seen?.body?.sdl === undefined
+      ? false
+      : written.get(one.contract).satisfies(seen.body.sdl);
+  };
+
+  const registry = Registry({
+    memory,
+    adminMine,
+    modules: adminModules,
+    modulesFor,
+    announce,
+    forget,
+    vouched,
+    attest,
+    watch,
+  });
+  const admin = Being({
+    voice: adminVoice,
+    address,
+    modules: adminModules,
+    registry,
+    vouched,
+    watch,
+  });
+
+  announce(address);
+  for (const key of adminMine.list('identity/custody/')) {
+    announce(key.slice('identity/custody/'.length));
+  }
+
+  const held = (at) => at === address || adminMine.read(`identity/custody/${at}`) !== undefined;
+  const deliver = async (envelope) =>
+    held(envelope.to) ? receive(envelope, vouched) : wire.carry(paths.find(envelope.to), envelope);
+
+  // Client edge only — a resolver must never be handed this.
+  const resolve = (one) => (one === GROUND ? address : (adminMine.read(`aliases/${one}`) ?? one));
+
+  return Object.freeze({
+    address,
+    receive,
+    serve: (voice) => {
+      const client = Client({ voice, deliver, resolve });
+      const sdlOf = async (at) => (await client.describe(at))?.body?.sdl;
+      const asker = (at) => (source, variables) => client.ask(at, source, variables);
+      return Object.freeze({
+        address: client.address,
+        client,
+        gql: (at) =>
+          Object.freeze({
+            ask: asker(at),
+            introspect: () => client.introspect(at),
+            sdl: () => sdlOf(at),
+          }),
+        mcp: async (at) => {
+          const sdl = await sdlOf(at);
+          return sdl === undefined ? undefined : Mcp(sdl, asker(at));
+        },
+        pointer: async (at) => {
+          const sdl = await sdlOf(at);
+          return sdl === undefined ? undefined : Pointer(sdl, asker(at));
+        },
+      });
+    },
+  });
+};
+
+export { FLOOR, GROUND, Ground };

package/index.mjs

@@ -0,0 +1,10 @@
+export { ADMIN } from './admin.mjs';
+export { Blueprint, CLASSES, CORE_ONLY, OPEN, STRUCTURAL, coreClass, reads } from './blueprint.mjs';
+export { Client } from './client.mjs';
+export { Contract, Contracts } from './contract.mjs';
+export { GROUND, Ground } from './ground.mjs';
+export { Cells, Clock, Dns, Entropy, Keychain, Memory, Paths, Wire } from './modules.mjs';
+export { Mcp, Pointer } from './pointer.mjs';
+export { Program } from './program.mjs';
+export { MEASURE, Stamp, Tools } from './tools.mjs';
+export { Voice } from './voice.mjs';

package/modules.mjs

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { Tools } from './tools.mjs';
+
+const Cells = ({ file } = {}) => {
+  const cells = new Map(
+    file && existsSync(file) ? Object.entries(JSON.parse(readFileSync(file, 'utf8'))) : [],
+  );
+  const flush = () => {
+    if (file) {
+      writeFileSync(`${file}.next`, JSON.stringify(Object.fromEntries(cells)));
+      renameSync(`${file}.next`, file);
+    }
+  };
+  return Object.freeze({
+    drop: (prefix) => {
+      for (const cell of [...cells.keys()].filter((one) => one.startsWith(prefix))) {
+        cells.delete(cell);
+      }
+      flush();
+    },
+    dump: () => JSON.stringify(Object.fromEntries(cells)),
+    keys: (prefix) => [...cells.keys()].filter((cell) => cell.startsWith(prefix)),
+    peek: (cell) => cells.get(cell),
+    put: (cell, held) => {
+      cells.set(cell, held);
+      flush();
+    },
+  });
+};
+
+const Memory = (cells) => {
+  const held = (address, key) => cells.peek(`${address}/${key}`);
+  const writerAt = (address) => {
+    const chain = held(address, 'chain/pk');
+    return chain === undefined ? Tools.pkOf(address) : Buffer.from(chain.value, 'hex');
+  };
+  return Object.freeze({
+    list: (address, prefix) =>
+      cells.keys(`${address}/${prefix}`).map((cell) => cell.slice(address.length + 1)),
+
+    read: (address, key) => held(address, key),
+
+    replace: ({ address, pk, nextPkHash, sig }) => {
+      const committed = held(address, 'chain/nextPkHash');
+      if (committed === undefined || Tools.digest(Buffer.from(pk, 'hex')) !== committed.value) {
+        return undefined;
+      }
+      const version = committed.version + 1;
+      const claim = { address, nextPkHash, pk, version };
+      if (!Tools.verifies(Buffer.from(pk, 'hex'), Tools.canon(claim), sig)) {
+        return undefined;
+      }
+      cells.put(`${address}/chain/pk`, { value: pk, version });
+      cells.put(`${address}/chain/nextPkHash`, { value: nextPkHash, version });
+      return version;
+    },
+
+    write: ({ address, key, value, version, sig }) => {
+      if (key.startsWith('chain/') && version !== 1) {
+        return undefined;
+      }
+      const writer = writerAt(address);
+      if (writer === null || version !== (held(address, key)?.version ?? 0) + 1) {
+        return undefined;
+      }
+      if (!Tools.verifies(writer, Tools.canon({ address, key, value, version }), sig)) {
+        return undefined;
+      }
+      cells.put(`${address}/${key}`, { value, version });
+      return version;
+    },
+  });
+};
+
+const Clock = (ticks) => {
+  let at = 0;
+  return Object.freeze({ now: () => ticks[Math.min(at++, ticks.length - 1)] });
+};
+
+const Entropy = (grains) => {
+  let at = 0;
+  return Object.freeze({ grain: () => grains[Math.min(at++, grains.length - 1)] });
+};
+
+const Keychain = (secret) =>
+  Object.freeze({
+    seal: (value) => {
+      try {
+        return Tools.seal(secret, value);
+      } catch {
+        return undefined;
+      }
+    },
+    unseal: (sealed) => Tools.unseal(secret, sealed),
+  });
+
+const Dns = () => new Map();
+
+const Paths = (dns) =>
+  Object.freeze({
+    find: (address) => dns.get(address),
+    publish: (address, endpoint) =>
+      endpoint === undefined ? dns.delete(address) : dns.set(address, endpoint),
+  });
+
+const Wire = () =>
+  Object.freeze({
+    carry: async (endpoint, envelope) => (endpoint === undefined ? undefined : endpoint(envelope)),
+  });
+
+export { Cells, Clock, Dns, Entropy, Keychain, Memory, Paths, Wire };

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "nervur",
-  "version": "0.3.0",
-  "description": "The nervur CLI — a client of a running carcass, never the runtime (papers/host.md).",
+  "version": "0.6.0",
+  "description": "A distributed system of sovereign beings — one door, one question: by whose authority.",
+  "license": "Apache-2.0",
+  "author": "Razvan Gherghina",
+  "homepage": "https://nervur.org",
   "type": "module",
-  "bin": {
-    "nervur": "nervur.js"
+  "exports": {
+    ".": "./index.mjs"
   },
   "files": [
-    "nervur.js",
-    "preflight.js",
-    "scaffold.js",
-    "completion.js",
-    "style.js"
+    "*.mjs",
+    "NOTICE"
   ],
-  "dependencies": {
-    "@nervur-org/kit": "^0.1.0"
+  "engines": {
+    "node": ">=22"
   },
-  "license": "Apache-2.0"
+  "dependencies": {
+    "graphql": "^17.0.2"
+  }
 }

package/pointer.mjs

@@ -0,0 +1,79 @@
+import { buildSchema, getNamedType, isAbstractType, isObjectType } from 'graphql';
+
+const JSON_TYPE = { Boolean: 'boolean', Float: 'number', ID: 'string', Int: 'integer' };
+
+const selection = (type, depth) => {
+  const named = getNamedType(type);
+  if (!isObjectType(named) || depth === 0) {
+    return '';
+  }
+  const fields = Object.values(named.getFields())
+    .filter(
+      (one) =>
+        !one.args.some((arg) => String(arg.type).endsWith('!') && arg.defaultValue === undefined),
+    )
+    .filter((one) => !isAbstractType(getNamedType(one.type)))
+    .filter((one) => depth > 1 || !isObjectType(getNamedType(one.type)))
+    .map((one) => `${one.name}${selection(one.type, depth - 1)}`);
+  return fields.length === 0 ? '' : ` { ${fields.join(' ')} }`;
+};
+
+const document = (kind, field, args) => {
+  const used = field.args.filter((one) => args[one.name] !== undefined);
+  const names = used.map((one) => `$${one.name}: ${one.type}`).join(', ');
+  const pass = used.map((one) => `${one.name}: $${one.name}`).join(', ');
+  return `${kind}${names ? `(${names})` : ''} { ${field.name}${
+    pass ? `(${pass})` : ''
+  }${selection(field.type, 3)} }`;
+};
+
+const roots = (schema) =>
+  ['query', 'mutation'].flatMap((kind) => {
+    const type = kind === 'query' ? schema.getQueryType() : schema.getMutationType();
+    return type === undefined || type === null
+      ? []
+      : Object.values(type.getFields()).map((field) => ({ field, kind }));
+  });
+
+const calls = (sdl, ask) => {
+  const schema = buildSchema(sdl);
+  return roots(schema).map(({ field, kind }) => ({
+    field,
+    kind,
+    run: async (args = {}) => {
+      const answered = await ask(document(kind, field, args), args);
+      return answered?.body?.data?.[field.name];
+    },
+  }));
+};
+
+const Pointer = (sdl, ask) =>
+  Object.freeze(Object.fromEntries(calls(sdl, ask).map((one) => [one.field.name, one.run])));
+
+const Mcp = (sdl, ask) => {
+  const held = calls(sdl, ask);
+  return Object.freeze({
+    call: (name, args) => held.find((one) => one.field.name === name)?.run(args),
+    tools: held.map(({ field, kind }) =>
+      Object.freeze({
+        annotations: { readOnlyHint: kind === 'query' },
+        description: field.description ?? undefined,
+        inputSchema: {
+          properties: Object.fromEntries(
+            field.args.map((one) => [
+              one.name,
+              { type: JSON_TYPE[getNamedType(one.type).name] ?? 'string' },
+            ]),
+          ),
+          required: field.args
+            .filter((one) => String(one.type).endsWith('!'))
+            .map((one) => one.name),
+          type: 'object',
+        },
+        name: field.name,
+      }),
+    ),
+  });
+};
+
+export { Mcp, Pointer };

package/program.mjs

@@ -0,0 +1,74 @@
+import {
+  buildSchema,
+  defaultFieldResolver,
+  getIntrospectionQuery,
+  graphql,
+  isObjectType,
+} from 'graphql';
+import { Blueprint } from './blueprint.mjs';
+
+const bound = (blueprint) => {
+  const schema = blueprint.schema;
+  for (const type of Object.values(schema.getTypeMap())) {
+    if (!isObjectType(type) || type.name.startsWith('__')) {
+      continue;
+    }
+    for (const [field, held] of Object.entries(type.getFields())) {
+      const resolver = blueprint.resolvers[type.name]?.[field] ?? defaultFieldResolver;
+      held.resolve = (source, args, context, info) =>
+        blueprint.admits(type.name, field, context.rights)
+          ? resolver(source, args, context, info)
+          : null;
+    }
+  }
+  return schema;
+};
+
+const Program = (source) => {
+  const blueprint = Blueprint(source);
+  if (blueprint === undefined || blueprint.trespass.length > 0) {
+    return undefined;
+  }
+  const schema = bound(blueprint);
+  const curtained = new Map();
+  const seenBy = (held) => {
+    if (!curtained.has(held)) {
+      try {
+        curtained.set(held, buildSchema(blueprint.sdlFor(held)));
+      } catch {
+        curtained.set(held, undefined);
+      }
+    }
+    return curtained.get(held);
+  };
+  return Object.freeze({
+    ask: async ({ source: asked, variables, context }) => {
+      const answered = await graphql({
+        contextValue: context,
+        schema,
+        source: asked,
+        variableValues: variables,
+      });
+      return answered.errors === undefined ? { data: answered.data } : undefined;
+    },
+    bindings: blueprint.bindings,
+    classOf: blueprint.classOf,
+    config: blueprint.config,
+    declares: blueprint.declares,
+    digest: blueprint.digest,
+    introspect: async (held) => {
+      const filtered = seenBy(held);
+      if (filtered === undefined) {
+        return undefined;
+      }
+      const answered = await graphql({ schema: filtered, source: getIntrospectionQuery() });
+      return answered.errors === undefined ? answered.data : undefined;
+    },
+    modules: blueprint.modules,
+    name: blueprint.name,
+    rights: blueprint.rights,
+    sdlFor: blueprint.sdlFor,
+  });
+};
+
+export { Program };