@factoidal/core 0.7.1 → 0.11.0

package/solid/client/README.md

@@ -0,0 +1,100 @@
+# `@factoidal/core/solid/client` — a `fetch` host for the Solid Protocol
+
+The Solid Protocol v0.11.0 client conformance class
+(<https://solidproject.org/TR/protocol>) over the platform `fetch`.
+
+Tracking issue: <https://github.com/danbri/factoidal/issues/659>.
+Design record:
+[`docs/designissues/2026-09-06-lws-and-solid-protocols.md`](../../../../docs/designissues/2026-09-06-lws-and-solid-protocols.md).
+Conformance ledger:
+[`docs/lws-solid-conformance.md`](../../../../docs/lws-solid-conformance.md).
+
+## What is here and what is not
+
+`index.mjs` calls `solidClientRequest` to obtain a request record, puts
+that record on the wire, and gives the reply to `solidClientResponse` to
+be interpreted. Every request the client sends was built by the engine
+and every response it reports was read by the engine.
+
+This file composes no URL, sets no `Content-Type`, adds no `Slug`, reads
+no `Link` header and parses no body. Discovery, request construction,
+response interpretation and the WebID profile read are in
+`formal/lean4/L4Factoidal/Solid/Client/`.
+
+It shares no code with the server host beyond the engine loader.
+
+## The wasm contract
+
+| op | arguments | answer |
+| --- | --- | --- |
+| `solidClientRequest` | `[kind, argsJson]` | `{ ok, request }` |
+| `solidClientResponse` | `[kind, responseJson]` | `{ ok, interpretation }` |
+
+The two operations take different kind vocabularies and this host keeps
+them apart rather than deriving one from the other:
+
+* request kinds — `read`, `create`, `replace`, `patch`, `delete`,
+  `discoverStorage`, `readProfile`;
+* interpretation kinds — `storage`, `containment`, `auxiliaries`,
+  `profile`, `wacAllow`.
+
+Which interpretation a reply wants is a protocol decision, so this file
+never picks one. It uses the `interpret` member the request envelope
+named, then the `interpret` the caller passed. With neither, the reply is
+returned uninterpreted and `interpretation` is `null` — the raw record,
+never a host reading of it.
+
+A multi-step operation is a loop, not a special case. An interpretation
+that answers `{ continue: true, state }` sends the state back into the
+next `solidClientRequest`; walking from a resource up to its storage root
+is the case that needs it. A single-request operation runs the loop once.
+The loop is capped (`maxSteps`, default 16) so a state that never settles
+is a reported failure rather than a hang.
+
+The full contract is `docs/lws-solid-conformance.md`, section "wasm ABI".
+
+## Use
+
+```js
+import { createSolidClient } from '@factoidal/core/solid/client'
+
+const client = await createSolidClient({ baseIri: 'https://pod.example/' })
+const storage = await client.discoverStorage('/alice/notes/one')
+await client.replace('/alice/notes/one', '<#a> <#b> <#c> .', 'text/turtle')
+const read = await client.read('/alice/notes/one')
+await client.delete('/alice/notes/one')
+```
+
+```
+factoidal solid-client get https://pod.example/alice/notes/one
+factoidal solid-client put https://pod.example/alice/notes/one \
+  --file note.ttl --content-type text/turtle
+factoidal solid-client discover https://pod.example/alice/notes/one
+```
+
+## Exports
+
+| name | what it is |
+| --- | --- |
+| `createSolidClient(options)` | a client bound to one engine and one `fetch` |
+| `solidClientOpsAvailable(engine)` | probe the loaded module for the ops |
+| `SOLID_CLIENT_OPS` | the two op names |
+| `SOLID_REQUEST_KINDS` | the seven request kinds the ABI names |
+| `SOLID_INTERPRETATION_KINDS` | the five interpretation kinds |
+| `SolidClientHostError` | a host failure, with `unknownOp` |
+
+`options.fetch` replaces the platform `fetch`, which is how a test drives
+the client at an in-process server without a proxy. `options.baseIri`
+says where to send a request whose target the engine wrote as a path;
+an absolute target is used verbatim.
+
+The command's five verbs are aliases for the request kinds — `get`→`read`,
+`put`→`replace`, `post`→`create`, `delete`→`delete`,
+`discover`→`discoverStorage` — and a kind name is accepted directly.
+
+## Tests and interop
+
+```
+node tests/solid/client/against-own-server.mjs   # against our own server
+bash tools/solid-client-interop.sh               # against Community Solid Server
+```

package/solid/client/index.mjs

@@ -0,0 +1,293 @@
+// A `fetch` host for the Solid Protocol v0.11.0 client conformance class.
+// https://github.com/danbri/factoidal/issues/659
+// Design record: docs/designissues/2026-09-06-lws-and-solid-protocols.md
+// Specification: https://solidproject.org/TR/protocol
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Call `solidClientRequest` to get a request record, put that record on
+// the wire with `fetch`, and give the reply to `solidClientResponse` to
+// be interpreted. It is a socket and nothing else.
+//
+// It composes no URL, sets no `Content-Type`, adds no `Slug`, reads no
+// `Link` header and parses no body. Discovery, request construction,
+// response interpretation and the WebID profile read are in
+// `formal/lean4/L4Factoidal/Solid/Client/` (iron rule 7 of CLAUDE.md).
+// A reviewer who finds a header name, a media type or a link relation
+// in this file has found a rule violation.
+//
+// THE WASM CONTRACT
+// Fixed in docs/lws-solid-conformance.md, section "wasm ABI".
+//   solidClientRequest  [kind, argsJson]     -> { ok, request }
+//   solidClientResponse [kind, responseJson] -> { ok, interpretation }
+//
+//   request  { method, target, headers: [[name, value]], body }
+//   response { status, headers: [[name, value]], body, target }
+//
+// The `target` of a response record is the request target the reply
+// answers, echoed back from the request the engine built. The `storage`
+// interpretation needs it to move up the path hierarchy.
+//
+// The two operations take DIFFERENT kind vocabularies, and this host
+// keeps them apart rather than deriving one from the other.
+//
+//   request kinds:        read, create, replace, patch, delete,
+//                         discoverStorage, readProfile
+//   interpretation kinds: storage, containment, auxiliaries, profile,
+//                         wacAllow
+//
+// Which interpretation a reply wants is a protocol decision, so this
+// file never picks one. It uses, in order: the `interpret` member the
+// request envelope named, then the `interpret` the caller passed. With
+// neither, the reply is returned uninterpreted and `interpretation` is
+// null -- the raw record, never a host reading of it.
+//
+// A multi-step operation is a loop, not a special case: an
+// interpretation that answers `{ continue: true, state }` sends the
+// state back into the next `solidClientRequest`. Walking from a resource
+// up to its storage root is the case that needs it. A single-request
+// operation runs the loop once, and the loop is capped so a state that
+// never settles is a reported failure rather than a hang.
+//
+// This file shares no code with `../server/index.mjs` beyond the engine
+// loader.
+
+import { loadEngine } from '../../bin/engine.mjs'
+
+/** The ops this host needs from the engine. */
+export const SOLID_CLIENT_OPS = ['solidClientRequest', 'solidClientResponse']
+
+/** The request kinds the ABI names. Listed so a caller can be checked
+ *  against the contract; this host attaches no meaning to any of them. */
+export const SOLID_REQUEST_KINDS = [
+  'read', 'create', 'replace', 'patch', 'delete', 'discoverStorage', 'readProfile'
+]
+
+/** The interpretation kinds the ABI names. */
+export const SOLID_INTERPRETATION_KINDS = [
+  'storage', 'containment', 'auxiliaries', 'profile', 'wacAllow', 'created'
+]
+
+/** An error raised by the Solid client host. `unknownOp` is set when the
+ *  loaded WebAssembly module does not carry the operation at all. */
+export class SolidClientHostError extends Error {
+  constructor (message, detail = {}) {
+    super(message)
+    this.name = 'SolidClientHostError'
+    this.unknownOp = detail.unknownOp === true
+  }
+}
+
+function isUnknownOp (error) {
+  const text = error && error.message ? String(error.message) : String(error)
+  return text.indexOf('unknown op') >= 0
+}
+
+/**
+ * Whether the loaded engine carries the Solid client operations.
+ *
+ * @param {object} engine the handle from `loadEngine()`
+ * @returns {Promise<{available: boolean, reason: string}>}
+ */
+export async function solidClientOpsAvailable (engine) {
+  try {
+    engine.call('solidClientRequest', ['read', JSON.stringify({ target: '/' })])
+    return { available: true, reason: 'solidClientRequest answered' }
+  } catch (error) {
+    if (isUnknownOp(error)) {
+      return {
+        available: false,
+        reason: 'the loaded l4factoidal WebAssembly module does not carry ' +
+          'the solid client ops (rebuild formal/lean4/Wasm)'
+      }
+    }
+    return { available: true, reason: 'solidClientRequest answered with an engine error' }
+  }
+}
+
+function requestOf (envelope) {
+  if (envelope === null || typeof envelope !== 'object') {
+    throw new SolidClientHostError('solidClientRequest answered with no envelope')
+  }
+  const record = (envelope.request !== null && typeof envelope.request === 'object')
+    ? envelope.request
+    : envelope
+  if (typeof record.method !== 'string' || typeof record.target !== 'string') {
+    throw new SolidClientHostError(
+      'solidClientRequest answered with no method and target')
+  }
+  return {
+    method: record.method,
+    target: record.target,
+    headers: Array.isArray(record.headers) ? record.headers : [],
+    body: typeof record.body === 'string' ? record.body : null
+  }
+}
+
+function interpretationOf (envelope) {
+  if (envelope === null || typeof envelope !== 'object') {
+    throw new SolidClientHostError('solidClientResponse answered with no envelope')
+  }
+  return (envelope.interpretation !== null && typeof envelope.interpretation === 'object')
+    ? envelope.interpretation
+    : envelope
+}
+
+/** The reply as the JSON response record the contract states. */
+async function recordOfReply (reply) {
+  const headers = []
+  reply.headers.forEach((value, name) => { headers.push([name, value]) })
+  return { status: reply.status, headers, body: await reply.text() }
+}
+
+/**
+ * A Solid client bound to one engine and one `fetch`.
+ *
+ * @param {object} [options]
+ * @param {object} [options.engine] an engine handle to reuse
+ * @param {Function} [options.fetch] the fetch to use (default `globalThis.fetch`)
+ * @param {string} [options.baseIri] prefixed to a request target that is a path
+ * @param {number} [options.maxSteps] the loop cap for a multi-step operation
+ * @returns {Promise<object>} the client
+ */
+export async function createSolidClient (options = {}) {
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const wire = typeof options.fetch === 'function' ? options.fetch : globalThis.fetch
+  if (typeof wire !== 'function') {
+    throw new SolidClientHostError('no fetch is available in this runtime')
+  }
+  const maxSteps = typeof options.maxSteps === 'number' ? options.maxSteps : 16
+  const baseIri = typeof options.baseIri === 'string' ? options.baseIri : null
+
+  /** Where to send a request whose target the engine wrote. The engine
+   *  resolves the target against baseIri (RFC 3986 section 5.2, op
+   *  resolveIri) and says whether it was already absolute
+   *  (https://github.com/danbri/factoidal/issues/894 item 5). */
+  function endpoint (target) {
+    let r
+    try {
+      r = engine.call('resolveIri', [baseIri === null ? '' : baseIri, String(target)])
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new SolidClientHostError(
+          'the loaded l4factoidal WebAssembly module does not carry the ' +
+          'resolveIri operation; rebuild it with formal/lean4/Wasm/build-wasm.sh')
+      }
+      throw error
+    }
+    if (r.referenceAbsolute) return String(target)
+    if (baseIri === null) {
+      throw new SolidClientHostError(
+        `the engine answered the relative reference "${target}" and this client has no ` +
+        'baseIri to resolve it against; pass baseIri to createSolidClient')
+    }
+    return r.iri
+  }
+
+  function callRequest (kind, args) {
+    try {
+      return engine.call('solidClientRequest', [kind, JSON.stringify(args)])
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new SolidClientHostError(
+          'the loaded l4factoidal WebAssembly module does not carry ' +
+          'solidClientRequest', { unknownOp: true })
+      }
+      throw error
+    }
+  }
+
+  function callResponse (kind, record) {
+    try {
+      return engine.call('solidClientResponse', [kind, JSON.stringify(record)])
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new SolidClientHostError(
+          'the loaded l4factoidal WebAssembly module does not carry ' +
+          'solidClientResponse', { unknownOp: true })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Run one client operation to its end.
+   *
+   * @param {string} kind a request kind from `SOLID_REQUEST_KINDS`
+   * @param {object} args the operation's arguments, passed unread
+   * @param {object} [extra] `interpret`: an interpretation kind to use
+   *   when the request envelope names none
+   * @returns {Promise<{kind: string, request: object, response: object,
+   *                    interpret: string|null, interpretation: object|null,
+   *                    steps: number}>}
+   */
+  async function run (kind, args, extra = {}) {
+    let state = null
+    for (let step = 1; step <= maxSteps; step += 1) {
+      const built = callRequest(kind, state === null ? args : { ...args, state })
+      const request = requestOf(built)
+      const headers = {}
+      for (const pair of request.headers) {
+        if (!Array.isArray(pair) || pair.length < 2) continue
+        headers[pair[0]] = headers[pair[0]] === undefined
+          ? String(pair[1])
+          : `${headers[pair[0]]}, ${String(pair[1])}`
+      }
+      const reply = await wire(endpoint(request.target), {
+        method: request.method,
+        headers,
+        // fetch refuses any body on GET and HEAD, even an empty string; the
+        // engine's record carries "" there, which is the same message.
+        body: (request.body === null || request.method === 'GET' || request.method === 'HEAD')
+          ? undefined : request.body,
+        redirect: 'manual'
+      })
+      const record = await recordOfReply(reply)
+      const interpretKind = typeof built.interpret === 'string'
+        ? built.interpret
+        : (typeof extra.interpret === 'string' ? extra.interpret : null)
+      const answer = {
+        kind,
+        request,
+        response: record,
+        interpret: interpretKind,
+        interpretation: null,
+        steps: step
+      }
+      if (interpretKind === null) return answer
+      // The record says what came back; `target` says what was asked. The
+      // storage walk needs both, and this is the engine's own target
+      // echoed back, not a URL this file composed. `requestUri` is the URL
+      // the request went to (the `endpoint` call above): the base IRI of
+      // the representation (RFC 3986 §5.1.3), which the engine resolves
+      // relative references against.
+      const interpretation = interpretationOf(
+        callResponse(interpretKind, { ...record, target: request.target,
+          requestUri: endpoint(request.target) }))
+      answer.interpretation = interpretation
+      if (interpretation.continue !== true) return answer
+      state = interpretation.state === undefined ? null : interpretation.state
+    }
+    throw new SolidClientHostError(
+      `the "${kind}" operation did not finish within ${maxSteps} requests`)
+  }
+
+  return {
+    engine,
+    run,
+    /** Named wrappers over `run`. Each one passes its arguments through;
+     *  none of them adds a header, a media type or a URL. */
+    read: (target, extra = {}) => run('read', { target, ...extra }),
+    create: (target, body, contentType, extra = {}) =>
+      run('create', { target, body, contentType, ...extra }),
+    replace: (target, body, contentType, extra = {}) =>
+      run('replace', { target, body, contentType, ...extra }),
+    patch: (target, body, contentType, extra = {}) =>
+      run('patch', { target, body, contentType, ...extra }),
+    delete: (target, extra = {}) => run('delete', { target, ...extra }),
+    discoverStorage: (target, extra = {}) =>
+      run('discoverStorage', { target, interpret: 'storage', ...extra },
+        { interpret: 'storage' }),
+    readProfile: (target, extra = {}) =>
+      run('readProfile', { target, ...extra }, { interpret: 'profile' })
+  }
+}

package/solid/server/README.md

@@ -0,0 +1,96 @@
+# `@factoidal/core/solid/server` — a Node host for the Solid Protocol
+
+The Solid Protocol v0.11.0 server conformance class
+(<https://solidproject.org/TR/protocol>) served over Node's `http`
+module.
+
+Tracking issue: <https://github.com/danbri/factoidal/issues/659>.
+Design record:
+[`docs/designissues/2026-09-06-lws-and-solid-protocols.md`](../../../../docs/designissues/2026-09-06-lws-and-solid-protocols.md).
+Conformance ledger:
+[`docs/lws-solid-conformance.md`](../../../../docs/lws-solid-conformance.md).
+
+## What is here and what is not
+
+`index.mjs` is a socket, a body reader and a header writer. Storage
+discovery (`Link: rel="type"` for `pim:Storage`), containment triples,
+slash semantics, `Allow` and the `Accept-*` family, the PUT/POST/PATCH/
+DELETE rules with their status codes, the `acl` and `describedby`
+auxiliary lifecycle, N3 Patch, Web Access Control, CORS and the LDN
+inbox are all in `formal/lean4/L4Factoidal/Solid/Server/` and reach this
+file only as a `{status, headers, body}` record.
+
+The CORS preflight is not an exception. An `OPTIONS` request goes to
+`solidStep` like any other and the engine's headers are written back
+unread. The only status this file writes itself is `500`, for a failure
+of the host.
+
+Solid defers to LWS in the engine, not here: `Solid/Server/*`
+instantiates `LWS.Store` and refines `LWS.Operations.step`. This host
+knows nothing of that layering.
+
+## The wasm contract
+
+| op | arguments | answer |
+| --- | --- | --- |
+| `solidOpen` | `[configJson]` | `{ ok, handle, root, storage }` |
+| `solidStep` | `[handle, requestJson]` | `{ ok, response }` |
+| `solidClose` | `[handle]` | `{ ok }` |
+
+```
+request  { method, target, headers: [[name, value]], body }
+response { status, headers: [[name, value]], body }
+```
+
+`configJson` members, all optional: `baseIri` (the absolute IRI the
+storage root maps to), `now` (the engine clock in seconds, advancing one
+second per mutation), `owner` (the WebID advertised through
+`Link: rel="…solid/terms#owner"`) and `agent` (the WebID of the
+requesting agent). With an ephemeral port the origin is not known until
+the socket is bound, so `listen` binds first and opens the storage
+after. `target` is a path within the storage; this host composes no IRI.
+
+`agent` is where authentication meets the engine. Verifying a Solid-OIDC
+token is a host job and is not built yet, so a handle with no `agent` is
+an unauthenticated agent, which is what the first slice serves. Web
+Access Control decisions are the engine's, over the agent the host
+verified.
+
+The full contract is `docs/lws-solid-conformance.md`, section "wasm ABI".
+
+A module built before these ops landed answers `unknown op`.
+`solidServerOpsAvailable(engine)` reports that, and `tests/solid/server/`
+skips with the reason printed.
+
+## Use
+
+```js
+import { listen } from '@factoidal/core/solid/server'
+
+const running = await listen({ port: 3000, baseIri: 'https://pod.example/' })
+console.log(running.origin)
+await running.close()
+```
+
+```
+factoidal solid-serve /var/lib/solid --port 3000 --base https://pod.example/
+```
+
+## Exports
+
+| name | what it is |
+| --- | --- |
+| `listen(options)` | start a server, resolve when it is listening |
+| `createSolidServer(options)` | build the server without listening |
+| `openSolidStorage(options)` | open a handle and get `step` / `close` |
+| `solidServerOpsAvailable(engine)` | probe the loaded module for the ops |
+| `SOLID_SERVER_OPS` | the three op names |
+| `SolidServerHostError` | a host failure, with `unknownOp` |
+
+## Tests and interop
+
+```
+node tests/solid/server/protocol.mjs
+bash tools/solid-server-interop.sh        # solid-crud-tests + WAC tests
+bash tools/solid-conformance-harness.sh   # the Gherkin harness, needs Docker
+```