prolog-notebook 0.1.2 → 0.3.0

package/src/session.js

@@ -0,0 +1,227 @@
+// The async session interface, and the in-process implementation of it.
+//
+// Everything above the engine talks to this, never to PrologSession directly. The
+// methods return promises whether or not the work is actually asynchronous,
+// because one of the two implementations runs the engine in a worker and the
+// other does not, and a caller that has to know which is a caller that will one
+// day be ported wrongly.
+//
+//     await session.consult(text, 'cell-p-family')
+//     const query = session.query('is_son(X)')
+//     let r; while (!(r = await query.next()).done) …
+//     await session.abort()
+//
+// WHY ASYNC AT ALL: a Prolog query is synchronous WASM, so a non-terminating goal
+// blocks whatever thread it runs on — no timer fires, no button responds, nothing
+// repaints. Non-termination is chapter material in a Prolog book, so the engine
+// has to live somewhere that can be terminated. See docs/modes.md and 869ejgkfq.
+
+/**
+ * What every session replays after an abort.
+ *
+ * Abort is "throw the engine away and build a new one", which is only affordable
+ * because of a decision already made: one cell, one virtual file (869eddzfp), so
+ * the clause store is rebuilt from the cells in about 3.5 ms each. Nothing
+ * cooperative has to reach inside a running Prolog goal.
+ *
+ * Insertion order is document order, which is also execution order.
+ */
+export class ConsultLog {
+  constructor() {
+    this.entries = new Map();
+  }
+
+  record(name, text) {
+    // Re-consulting a cell replaces it, exactly as SWI does, so the log holds one
+    // entry per cell rather than a history of edits.
+    this.entries.set(name, text);
+  }
+
+  forget(name) {
+    this.entries.delete(name);
+  }
+
+  /**
+   * Is this cell already loaded, at exactly this text?
+   *
+   * What makes "Run consults the cells above it" cheap enough to do on every
+   * click: the second Run of a chapter consults nothing, because nothing has
+   * changed. An edited cell answers false for itself and only for itself.
+   */
+  isCurrent(name, text) {
+    return this.entries.has(name) && this.entries.get(name) === text;
+  }
+
+  clear() {
+    this.entries.clear();
+  }
+
+  *[Symbol.iterator]() {
+    for (const [name, text] of this.entries) yield { name, text };
+  }
+}
+
+/**
+ * Take one cell's clauses back out of a running engine.
+ *
+ * Shared by both sessions because it is not really a session operation at all —
+ * it is one consult and one log edit, and two copies of that would be two things
+ * to keep in step.
+ *
+ * HOW IT WORKS, because it looks like a trick and is not: one cell is one virtual
+ * file (869eddzfp), and consulting a file replaces the clauses that came from it.
+ * Consulting nothing therefore leaves nothing. This is SWI's own semantics, not
+ * bookkeeping of ours, so a predicate whose only clauses lived in this cell goes
+ * back to being genuinely unknown — and a query that calls it says so, exactly as
+ * a real toplevel would.
+ *
+ * There is deliberately NO dependency handling here. A cell that mentioned this
+ * one is untouched, because Prolog has no load-time name binding: `q(X) :- p(X)`
+ * merely mentions p/1 and looks it up when called. The consequence surfaces as an
+ * ordinary Prolog error at call time, which is the truth rather than a cascade we
+ * would have to invent.
+ *
+ * @param {{consult: Function, log: ConsultLog}} session
+ * @param {string} name
+ */
+export async function unconsult(session, name) {
+  if (!session.log.entries.has(name)) return { ok: true, unloaded: false };
+  const result = await session.consult('', name);
+  // Forgotten rather than recorded as empty, so a restart does not spend a
+  // consult loading nothing.
+  session.log.forget(name);
+  return { ...result, unloaded: result.ok };
+}
+
+let anonymousCells = 0;
+
+/**
+ * A consult with no cell name still needs a stable one, or the replay log cannot
+ * key it and an abort would lose it.
+ */
+export function defaultCellName() {
+  return `cell-anon-${++anonymousCells}`;
+}
+
+/**
+ * A session that runs the engine on the caller's own thread.
+ *
+ * Correct, simple, and NOT protected: a non-terminating goal hangs the process,
+ * because there is no second thread to notice. That is acceptable for Node — the
+ * CLI is not an interactive page and CI has its own timeouts — and it is stated
+ * here rather than implied, so nobody discovers it in a browser.
+ */
+export class InProcessSession {
+  /**
+   * @param {import('./engine.js').PrologSession} engine
+   * @param {() => Promise<import('./engine.js').PrologSession>} rebuild
+   */
+  constructor(engine, rebuild) {
+    this.engine = engine;
+    this.rebuild = rebuild;
+    this.log = new ConsultLog();
+    // The one query allowed to be open. See supersede() below.
+    this.open = null;
+  }
+
+  /**
+   * ONE OPEN SEQUENCE PER SESSION, and the reason is not tidiness.
+   *
+   * SWI keeps open queries on a stack and swipl-wasm enforces it: stepping or
+   * closing anything but the innermost throws "Attempt to access not innermost
+   * query". A page cannot promise the order — the order is whatever the reader
+   * clicks — so the constraint is met by construction instead: there is never
+   * more than one open query, which means the one being closed is always the
+   * innermost, which means the close is always legal (869epzqpc).
+   *
+   * The caller is told, through the query's own `onSuperseded`, because a
+   * sequence that ends without saying so is exactly the silence this replaces.
+   */
+  supersede() {
+    const previous = this.open;
+    this.open = null;
+    if (!previous) return;
+    // Straight to the engine's query: closing is synchronous in this process, and
+    // the frame must be gone before the next PL_open_query, not merely scheduled.
+    previous.query.close({ superseded: true });
+    previous.onSuperseded?.();
+  }
+
+  async consult(text, name = defaultCellName()) {
+    const result = this.engine.consult(text, name);
+    if (result.ok) this.log.record(name, text);
+    return result;
+  }
+
+  query(goal) {
+    // The frame opens here, in the engine's constructor, so the previous one has
+    // to be closed BEFORE this line rather than after: once a second query is
+    // open, the first is no longer innermost and can never be closed at all.
+    this.supersede();
+    const query = new InProcessQuery(this.engine.query(goal), this);
+    this.open = query;
+    return query;
+  }
+
+  async unconsult(name) {
+    return unconsult(this, name);
+  }
+
+  /**
+   * Discard the engine and replay the consults into a fresh one.
+   *
+   * In-process this can only happen BETWEEN operations — a goal that is already
+   * looping has the thread and will not give it back. Use the worker-backed
+   * session where that matters.
+   */
+  async restart() {
+    // Every frame died with the engine. Saying so here rather than leaving a
+    // handle that points into a heap that no longer exists.
+    this.open = null;
+    this.engine = await this.rebuild();
+    for (const { name, text } of this.log) this.engine.consult(text, name);
+  }
+
+  async abort() {
+    return this.restart();
+  }
+
+  async close() {}
+}
+
+// No formatSolution() on a session, deliberately. The engine-backed one renders
+// through SWI itself and the worker-backed one could not — it would have to fall
+// back to the engine-free spelling, so the same call would quietly mean two
+// different things depending on where it ran. Use `query.next().text`, which SWI
+// renders in both, or the exported formatSolution() when there is no engine at all.
+
+class InProcessQuery {
+  constructor(query, session) {
+    this.query = query;
+    this.session = session;
+    /** Set by the caller to hear that its sequence was closed for another one. */
+    this.onSuperseded = null;
+  }
+
+  async next() {
+    const r = this.query.next();
+    if (r.done) this.#release();
+    return r;
+  }
+
+  async all(limit) {
+    const r = this.query.all(limit);
+    this.#release();
+    return r;
+  }
+
+  async close(options) {
+    this.query.close(options);
+    this.#release();
+  }
+
+  /** The frame is gone, so this query is no longer the one holding the session's. */
+  #release() {
+    if (this.session?.open === this) this.session.open = null;
+  }
+}

package/src/version.js

@@ -0,0 +1,51 @@
+// Who this is, in one place, for everything that has to say so.
+//
+// The command reads package.json at run time; a page cannot — there is no
+// filesystem behind a `<script type="module">` and no build step to inline
+// anything. So the facts live here, as constants both can import, and tests
+// assert that they still agree with package.json and with LICENSE. Two files to
+// touch at release, and a suite that fails loudly when only one of them is.
+
+/** The name a person would say. `prolog-notebook` is what npm installs. */
+export const NAME = 'Prolog Notebook';
+
+/** Must equal package.json's `version` — test/run.test.mjs enforces it. */
+export const VERSION = '0.3.0';
+
+/** The two facts a licence notice is actually made of. */
+export const YEAR = '2026';
+export const HOLDER = 'Johnny Jarecsni';
+
+/** Must agree with LICENSE on the year and the holder. Same enforcement. */
+export const COPYRIGHT = `Copyright (C) ${YEAR} ${HOLDER}`;
+
+export const LICENSE = 'MIT';
+
+/**
+ * The line a command prints and a page shows in its panel, so the two cannot
+ * describe the same release differently.
+ *
+ * @returns {string} e.g. "Prolog Notebook v0.2.0 - Copyright (C) 2026 … , MIT License."
+ */
+export function banner() {
+  return `${NAME} v${VERSION} - ${COPYRIGHT}, ${LICENSE} License.`;
+}
+
+/**
+ * The same facts for a page, which has a card to fit them in rather than a
+ * terminal to fill.
+ *
+ * TWO SHORT LINES BY CONSTRUCTION, not by shrinking the type: what is running,
+ * then who owns it. The engine's version joins the first line once it is known,
+ * because that line is the identity of the thing doing the work — and `©` rather
+ * than `Copyright (C)` because that is how a page writes it, while the words in
+ * both come from the same constants.
+ *
+ * @returns {{running: string, legal: string}}
+ */
+export function colophon() {
+  return {
+    running: `${NAME} v${VERSION}`,
+    legal: `© ${YEAR} ${HOLDER} · ${LICENSE} License`,
+  };
+}

package/src/worker.js

@@ -0,0 +1,77 @@
+// The engine's home. A CLASSIC worker, deliberately.
+//
+// swipl-wasm ships only UMD/global scripts — `var SWIPL = …` at top level, with no
+// ESM export — so a module worker's `import()` would hand back an empty namespace.
+// importScripts is the only thing that puts SWIPL where we can reach it. Our own
+// engine is an ES module, and dynamic import() works fine inside a classic worker,
+// so nothing has to be bundled or duplicated to get both here.
+//
+// Everything in this file is protocol plumbing. The Prolog lives in engine.js and
+// is not aware it is in a worker.
+
+/* global importScripts */
+
+let session = null;
+const queries = new Map();
+let nextQueryId = 1;
+
+self.onmessage = async ({ data }) => {
+  const { id, op } = data;
+  try {
+    self.postMessage({ id, ok: true, value: await handle(op, data) });
+  } catch (error) {
+    self.postMessage({ id, ok: false, error: error?.message ?? String(error) });
+  }
+};
+
+async function handle(op, args) {
+  switch (op) {
+    case 'boot': {
+      importScripts(args.swiplUrl);
+      const { PrologSession } = await import(args.engineUrl);
+      if (typeof self.SWIPL !== 'function') {
+        throw new Error(`swipl-wasm did not define SWIPL after loading ${args.swiplUrl}`);
+      }
+      session = await PrologSession.create(self.SWIPL, args.options ?? {});
+      return true;
+    }
+
+    case 'consult':
+      return session.consult(args.text, args.name);
+
+    case 'open': {
+      const qid = nextQueryId++;
+      queries.set(qid, session.query(args.goal));
+      return qid;
+    }
+
+    case 'next': {
+      const query = queries.get(args.qid);
+      if (!query) throw new Error(`no open query ${args.qid}`);
+      const result = query.next();
+      if (result.done) queries.delete(args.qid);
+      return result;
+    }
+
+    case 'all': {
+      const query = queries.get(args.qid);
+      if (!query) throw new Error(`no open query ${args.qid}`);
+      queries.delete(args.qid);
+      return query.all(args.limit);
+    }
+
+    case 'close': {
+      // CLOSING MUST REACH THE ENGINE. Forgetting the id here — which is all this
+      // did until 869epzqpc — leaves the query open inside SWI for the life of
+      // the session, and every later query then nests inside a frame nobody can
+      // ever step or release.
+      const query = queries.get(args.qid);
+      queries.delete(args.qid);
+      query?.close();
+      return true;
+    }
+
+    default:
+      throw new Error(`unknown worker op "${op}"`);
+  }
+}