@_linked/server 3.6.1 → 3.7.0

package/readme.md

@@ -409,11 +409,11 @@ A host that starts the app process (Create Now) controls it over HTTP routes on
 
 | Route | Answer |
 |---|---|
-| `GET /admin/health` | 200 `{status: 'ok'}` once the server listens (the boot shape sync has finished by then) |
+| `GET /admin/health` | 200 `{status: 'ok'}` once the server listens (the boot ontology sync, shape check and shape sync have finished by then) |
 | `POST /admin/restart` | 202, then the process exits; the host starts it again |
-| `POST /admin/sync-shapes` | 200 `{written, orphanScope, reloaded, shapes}` (or `{written: 0, skipped, …}` when shape sync is off); 400 `{error}` for a malformed body or a package it may not reload; 500 `{error}` when the sync fails or times out |
+| `POST /admin/sync-shapes` | 200 `{written, orphanScope, reloaded, shapes, ontologies: {written, skipped}, shapeCheck: {errors, warnings}}` (or `{written: 0, skipped, …}` when shape sync is off); 400 `{error}` for a malformed body or a package it may not reload; 500 `{error}` when the sync fails or times out |
 
-`POST /admin/sync-shapes` re-syncs the registered shapes into the app's data exactly as the boot does (core `syncShapes`: only shapes whose stored `core:shapeHash` differs are written, with the boot's orphan policy and `syncShapesOnBoot` / `LINKED_SYNC_SHAPES_ON_BOOT` switches). The optional body `{packages: [...]}` names packages whose source the host changed; each must be a valid npm package name and the app itself or one of its direct dependencies, never an `@_linked/*` package. In dev their modules are invalidated in Vite and their backends reloaded before the sync, so a shape file written a moment ago is registered; a built app reloads nothing. `reloaded` lists the packages actually reloaded and `shapes` the node shape IRIs registered afterwards, so the host can check that the shape it wrote is there. Syncs run one at a time, as the system; one that takes longer than `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120000) fails and releases the queue. A source reload by itself (HMR) never syncs shapes.
+`POST /admin/sync-shapes` runs the ontology sync and the shape check (see [Ontology sync and the shape check](#ontology-sync-and-the-shape-check)), then re-syncs the registered shapes into the app's data exactly as the boot does (core `syncShapes`: only shapes whose stored `core:shapeHash` differs are written, with the boot's orphan policy and `syncShapesOnBoot` / `LINKED_SYNC_SHAPES_ON_BOOT` switches). The optional body `{packages: [...]}` names packages whose source the host changed; each must be a valid npm package name and the app itself or one of its direct dependencies, never an `@_linked/*` package; the list only says what to reload, it never filters the syncs. In dev their modules are invalidated in Vite and their backends reloaded before the sync, so a shape file written a moment ago is registered; a built app reloads nothing. `reloaded` lists the packages actually reloaded and `shapes` the node shape IRIs registered afterwards, so the host can check that the shape it wrote is there. Syncs run one at a time, as the system; one that takes longer than `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120000) fails and releases the queue. A source reload by itself (HMR) never syncs shapes. A failed ontology sync does not stop the shape sync; the route then answers 500 with the ontology error.
 
 Side effects to expect:
 
@@ -421,6 +421,16 @@ Side effects to expect:
 - **A restart drops in-flight requests.** `POST /admin/restart` exits the process 50 ms after answering. A host that restarts an app whose server has no `sync-shapes` route (an older `@_linked/server`) to make its boot sync the shapes drops whatever that app was serving.
 - The channel listens on the app's public port, like every other route; only the secret protects it.
 
+### Ontology sync and the shape check
+
+Before its shape sync, at boot and on `POST /admin/sync-shapes`, the server:
+
+1. **Registers the installed packages' ontologies** (core `registerInstalledOntologies`): it imports `lib/esm/ontologies/*.register.js` of every linked package it discovered in the app's dependency tree, so a package the app only deep-imports shape files from (`@_linked/schema/shapes/Person`) is synced and checked too, and of every workspace package of the app (`linkedPackage: true` under its `workspaces`), which no package may import (a Create Now clone's `packages/<slug>-ont`). In dev, a package without a built `lib/` registers from `src/ontologies/*.register.ts` through Vite's `ssrLoadModule`; a built app skips it. A register module that fails is logged and the rest go on.
+2. **Syncs the ontologies** (core `syncOntologies`): the `rdfs:subClassOf` triples of every registered package's ontology data are written into the app's default dataset, so the store's RDFS view infers the class hierarchy. A package whose stored hash matches is skipped, so an unchanged sync writes nothing. `ontologies.written` and `ontologies.skipped` name the packages (a package whose data cannot be read is skipped with core's warning). Sync nodes of packages no longer registered are pruned only with `LINKED_SYNC_SHAPES_PRUNE_ORPHANS=true`, the shape sync's orphan policy.
+3. **Checks the shapes** against that hierarchy (core `checkShapeHierarchy`, with every package's `dependencies` and `peerDependencies`). A running app is never stopped by it: each finding is logged, and `shapeCheck` counts them by severity.
+
+The ontology sync follows the shape sync's switches (`syncShapesOnBoot`, `LINKED_SYNC_SHAPES_ON_BOOT`), at boot and on `POST /admin/sync-shapes` alike: with shape sync off, the route syncs neither ontologies nor shapes (it still registers the packages' ontologies and runs the shape check). `LINKED_SYNC_ONTOLOGIES_ON_BOOT=false` turns off only the boot's ontology sync. The in-memory class hierarchy (core `loadOntologyHierarchy`) is loaded at boot either way. A failed ontology sync at boot is logged and the boot goes on.
+
 ## Provider lifecycle and HMR
 
 Every provider — generic (`BackendProvider`) or shape-scoped (`ShapeProvider`) — has a lifecycle the framework drives:

package/lib/esm/data/server.json

@@ -1,47 +0,0 @@
-{
-  "@context": {
-    "dc": "http://purl.org/dc/elements/1.1/",
-    "owl": "http://www.w3.org/2002/07/owl#",
-    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
-    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
-    "server": "https://linked.cm/ont/server/"
-  },
-  "@graph": [
-    {
-      "@id": "server:LincdServer",
-      "@type": "rdfs:Class",
-      "rdfs:comment": "A HTTP server for LINCD applications, running on node.js.",
-      "rdfs:isDefinedBy": {
-        "@id": "server:"
-      },
-      "rdfs:label": "LINCD Server"
-    },
-    {
-      "@id": "server:NodeFileStore",
-      "@type": "rdfs:Class",
-      "rdfs:comment": "Stores quads in a file in JSONLD format. Made for node.js environments.",
-      "rdfs:isDefinedBy": {
-        "@id": "server:"
-      },
-      "rdfs:label": "Node file store"
-    },
-    {
-      "@id": "server:BackendFileStore",
-      "@type": "rdfs:Class",
-      "rdfs:comment": "A simple quad store for frontends that are served by a LINCD Nodejs Server. Quads get loaded and updated through API calls to the backend. All quads are loaded into local memory in the frontend upon initiation of the app.",
-      "rdfs:isDefinedBy": {
-        "@id": "server:"
-      },
-      "rdfs:label": "Backend file store"
-    },
-    {
-      "@id": "server:BackendStore",
-      "@type": "rdfs:Class",
-      "rdfs:comment": "A base class for backend quad stores. These are quad stores for frontends that are served by a LINCD Nodejs Server. Quads get loaded and updated through API calls to the backend. All quads are loaded into local memory in the frontend upon initiation of the app.",
-      "rdfs:isDefinedBy": {
-        "@id": "server:"
-      },
-      "rdfs:label": "Backend store"
-    }
-  ]
-}