@_linked/server 3.12.1 → 3.14.0

package/lib/esm/shapes/LinkedServer.d.ts

@@ -15,7 +15,7 @@ import { Shape } from '@_linked/core/shapes/Shape';
  * needs; a plain function, an arrow function or a non-function value is not.
  */
 export declare function isProviderClass(value: unknown): boolean;
-import { type ShapeSyncResult } from '../utils/adminChannel.js';
+import { type GraphContentAnswer } from '../utils/adminChannel.js';
 /**
  * Serve the local upload folder at `/uploads` (where `LocalFileStore` files are
  * reachable), with the headers for untrusted files.
@@ -82,7 +82,7 @@ export declare class LinkedServer extends Shape {
      * could not be loaded at all.
      */
     private linkedPackageDirs;
-    /** The app's own workspace packages (`linkedPackage: true`), by real path. */
+    /** The app's own workspace packages (`linked.kind` of a package), by real path. */
     private workspacePackageDirs;
     /** The names of the app's own workspace packages. */
     private workspacePackageNames;
@@ -108,12 +108,14 @@ export declare class LinkedServer extends Shape {
     private initOnlyBoot;
     /**
      * Sync this server's registered shapes into app data, one named graph per package (see
-     * utils/syncShapes): each package's shapes in `{package IRI}/graph/shapes`, from its built
+     * utils/syncShapes) in every dataset the storage routing needs it in (core's
+     * `syncShapeGraphsRouted`; the default dataset when nothing is pinned, and a graph routing no
+     * longer sends to the default dataset is dropped there): each package's shapes in
+     * `{package IRI}/graph/shapes`, from its built
      * `shapes.ttl` (an installed package without one gets no shape graph), the app's own packages
      * generated in process in dev (through Vite's loader), and the app's generated single-owner
-     * shapes in `{DATA_ROOT}/graph/shapes`. Runs at boot, after the ontology sync, and again when
-     * the host asks for it over the control channel ({@link resyncShapes}). A source reload (HMR)
-     * does not sync shapes by itself.
+     * shapes in `{DATA_ROOT}/graph/shapes`. Runs at boot, after the ontology sync. A source reload
+     * (HMR) does not sync shapes.
      *
      * A graph whose stored content hash matches is not written, so a sync of unchanged shapes
      * writes nothing. Shapes an earlier sync wrote into the default graph are removed there once
@@ -123,65 +125,82 @@ export declare class LinkedServer extends Shape {
      * Shape graphs of packages no longer registered stay unless the operator sets
      * `LINKED_SYNC_SHAPES_PRUNE_ORPHANS=true` — see `bootOrphanScope` in utils/syncShapes.
      *
-     * Opt-out via `linked.config` `syncShapesOnBoot` (default true); env
-     * LINKED_SYNC_SHAPES_ON_BOOT overrides for deployment. A host whose default
-     * dataset is a context router (one that can't write context-free) sets
-     * `syncShapesOnBoot: false` and syncs its shapes itself.
+     * Runs when {@link bootSyncs}: the app writes its own graphs and `linked.config` does not set
+     * `syncShapesOnBoot: false`. A host that writes the app's graphs (`LINKED_GRAPH_WRITER=host`)
+     * reads their content through `POST /admin/graph-content` ({@link graphContent}).
      */
     private materializeShapesIntoStore;
-    /** One shape sync into the default dataset; throws when it fails. */
+    /**
+     * Whether the boot syncs the shapes and the ontologies: the app writes its own graphs
+     * (`LINKED_GRAPH_WRITER` is `app`) and `linked.config` does not set `syncShapesOnBoot: false`.
+     */
+    private bootSyncs;
+    /** One shape sync, following the routing; throws when it fails in any dataset. */
     private syncRegisteredShapes;
     /** The root directory of a package with shapes: the app, a discovered linked package, or one the app resolves. */
     private shapePackageDir;
     /**
-     * Boot: one warning when routing pins the shape shapes or the ontology term shapes to a dataset
-     * other than the default one, since the syncs write into the default dataset only (see
-     * {@link syncPinWarning}).
+     * Boot: one line naming the datasets the boot syncs write into, when the routing sends any graph
+     * beyond the default dataset (see {@link syncTargetsLine}). Only for the syncs this boot runs.
      */
-    private warnOfSyncPins;
+    private logSyncTargets;
     /**
      * Boot: sync the registered ontologies into their graphs in app data and run the shape
      * check, before the shape sync (see utils/ontologySync). The sync follows the shape sync's
-     * switch (`syncShapesOnBoot`, `LINKED_SYNC_SHAPES_ON_BOOT`), plus the opt-out
-     * `LINKED_SYNC_ONTOLOGIES_ON_BOOT=false`; the in-memory class hierarchy is loaded either way.
+     * switch ({@link bootSyncs}); the in-memory class hierarchy is loaded either way.
      * Never stops the boot: failures and findings are logged.
      */
     private syncOntologiesOnBoot;
     /**
      * Every discovered linked package and every workspace package of the app registers its
      * ontologies (in dev, an unbuilt one through Vite), then the ontology sync (when
-     * `sync` is set) into the default dataset, then the shape check.
+     * `sync` is set), following the routing, then the shape check.
      * Orphaned ontology graphs (and earlier sync nodes) are pruned under the shape sync's orphan policy
      * (`LINKED_SYNC_SHAPES_PRUNE_ORPHANS`).
      */
     private runOntologyPhase;
-    /** Tail of the {@link resyncShapes} queue: one re-sync at a time. */
+    /** Tail of the graph content's queue: one request at a time. */
     private shapeSyncQueue;
     /**
-     * Re-sync the registered ontologies and shapes into app data, as the boot does,
-     * and report what was written: the ontology sync (every registered package,
-     * hash-skipped), the shape check's counts, then the shape sync. A failed ontology
-     * sync does not stop the shape sync; the run then fails with the ontology error. The host calls it (`POST /admin/sync-shapes`) after it
-     * changed the app's shape code, so the app — the only process that loads that
-     * code — writes its own shapes and their hashes.
+     * What the app's `'package'`-mode syncs would write, writing nothing (`POST /admin/graph-content`):
+     * per package its shape graph's Turtle and its ontology graph's N-Triples with the hash each
+     * record gets and its sources, and the app's own shape graph (`null` when it has no single-owner
+     * shapes; left out without `DATA_ROOT`). A host that writes the app's graphs itself
+     * (`LINKED_GRAPH_WRITER=host`) reads them here, after it changed the app's shape code: the app
+     * is the only process that loads that code.
      *
-     * `packages` names the packages whose source changed: the app itself or its
-     * direct dependencies, never `@_linked/*` ({@link assertReloadablePackages}). In
-     * dev (Vite) their modules are invalidated and their backends reloaded first
-     * ({@link onSourceChange}), so a shape added since the boot is registered before
-     * the sync; without Vite (a built app) nothing is reloaded. The answer names the
-     * packages reloaded and the node shapes registered after it, so the host can check
-     * that the shape it wrote is there. Runs as the system, never as the caller of a
-     * request, one at a time; a run that takes longer than
+     * `reload` names the packages whose source changed: the app itself or its direct dependencies
+     * (its `linked.unpublishedPackages` among them), never `@_linked/*`
+     * ({@link assertReloadablePackages}). In dev (Vite) their modules are invalidated and their
+     * backends reloaded first ({@link onSourceChange}), then the ontologies are registered again and
+     * the shape check runs, so a shape added since the boot is in the answer; without Vite (a built
+     * app) nothing is reloaded. `reloaded` names the packages reloaded. `packages` limits the
+     * answer. Each package's Turtle comes from where the shape sync takes it (an installed package
+     * without `shapes.ttl` has none: `withoutTurtle`).
+     * Refused with {@link AdminConflictError} unless both graph targets are `'package'`. Runs one at
+     * a time, as the system, never as the caller of a request; a run that takes longer than
      * `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120 s) fails and releases the queue.
      */
-    resyncShapes({ packages }?: {
+    graphContent({ packages, reload }?: {
         packages?: string[];
-    }): Promise<ShapeSyncResult>;
-    /** The packages a host may ask to reload: the app itself and its direct dependencies. */
+        reload?: string[];
+    }): Promise<GraphContentAnswer>;
+    /** Reload each of `packages` from disk (dev only); the ones actually reloaded. */
+    private reloadPackages;
+    /**
+     * Run `fn` in the graph content's queue (one at a time), as the system, failing it after
+     * `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120 s) and releasing the queue.
+     */
+    private inShapeSyncQueue;
+    /**
+     * The packages a host may ask to reload: the app itself and its direct dependencies, which
+     * include every package in its `linked.unpublishedPackages`, transitively
+     * ({@link listedPackageNames}). Read from disk on each call: a list written after the boot
+     * counts. A malformed list throws.
+     */
     private reloadablePackages;
     /**
-     * Re-read one package's source from disk (dev only); see {@link resyncShapes}.
+     * Re-read one package's source from disk (dev only); see {@link graphContent}.
      * Resolves whether it reloaded anything.
      */
     private reloadPackageFromDisk;
@@ -270,7 +289,8 @@ export declare class LinkedServer extends Shape {
     protected importModule(specifier: string): Promise<any>;
     /**
      * Filters local workspace packages to only those reachable from the app's
-     * dependency tree. Mirrors the logic used by `buildAll` in lincd-cli.
+     * dependency tree: `dependencies` and `linked.unpublishedPackages`, of the app
+     * and of each package reached. Mirrors the logic used by `buildAll` in the cli.
      */
     private filterPackagesByDependencyTree;
     resizeImage(req: any, res: any): Promise<void>;
@@ -291,7 +311,7 @@ export declare class LinkedServer extends Shape {
      * Reload one package's backend providers from source.
      *
      * Called by the CLI orchestrator's Vite watcher whenever a `.ts`/`.tsx`
-     * file inside a workspace package changes, and by {@link resyncShapes}.
+     * file inside a workspace package changes, and by {@link graphContent}.
      * Disposes the package's existing providers (so routes, listeners, timers
      * don't accumulate), drops them from the registry, and re-runs
      * indexPackageBackendProviders to pick up the freshly-imported module.

package/lib/esm/shapes/LinkedServer.js

@@ -36,11 +36,11 @@ import { paint } from '../utils/paint.js';
 import { nativeImport } from '../utils/nativeImport.js';
 import { createJsonBodyParser } from '../utils/jsonBodyParser.js';
 import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
-import { getAllShapeClasses, getShapeClass, getSuperShapesClasses, } from '@_linked/core/utils/ShapeClass';
+import { getShapeClass, getSuperShapesClasses, } from '@_linked/core/utils/ShapeClass';
 import path from 'path';
 import { pathToFileURL } from 'node:url';
 import { FatalStartupError, isFatalError } from '../utils/fatalError.js';
-import { discoverLinkedDependencies, hasModuleEntry, isBundledBySsr, NODE_IMPORT_CONDITIONS, readDependencyLists, readInstalledPackage, resolveBackendEntry, resolveDevBackendEntry, ssrNoExternalOf, } from '../utils/linkedDependencies.js';
+import { discoverLinkedDependencies, listedPackageNames, unpublishedNames, hasModuleEntry, isBundledBySsr, NODE_IMPORT_CONDITIONS, readDependencyLists, readInstalledPackage, resolveBackendEntry, resolveDevBackendEntry, ssrNoExternalOf, } from '../utils/linkedDependencies.js';
 /**
  * `instanceof ShapeProvider`, tolerating a second copy of server-utils.
  *
@@ -137,10 +137,11 @@ import { resolveStaticAccessURL, staticAssetURL, } from '../utils/releaseManifes
 import { resolveBootstrapEntry, resolveViteMainEntry, resolveViteServingMode, } from '../utils/bootstrapEntry.js';
 import { resolveRouteAssets } from '../utils/routeAssets.js';
 import { resolveRouteComponent, ssrCssInlineUrls, ssrCssScope, } from '../utils/ssrCss.js';
-import { appShapesGraph, bootOrphanScope, loadShapeGraphCore, syncShapeGraphsInto, viteShapesTurtleGenerator, } from '../utils/syncShapes.js';
-import { bootSyncsOntologies, loadOntologyCore, runOntologyPhase, ontologyPackageDirs, sourceModuleImporter, shapeSyncOn, syncOntologiesThenShapes, } from '../utils/ontologySync.js';
-import { applyGraphTargetsFromEnv, syncPinWarning } from '../utils/graphTargets.js';
-import { AdminRequestError, assertReloadablePackages, registerAdminRoutes, resolveAdminSecret, } from '../utils/adminChannel.js';
+import { appShapesGraph, bootOrphanScope, loadShapeGraphCore, graphContentOf, syncRoutedShapeGraphs, viteShapesTurtleGenerator, } from '../utils/syncShapes.js';
+import { loadOntologyCore, runOntologyPhase, ontologyPackageDirs, sourceModuleImporter, shapeSyncOn, } from '../utils/ontologySync.js';
+import { getGraphTargets } from '@_linked/core/utils/graphTargets';
+import { applyGraphTargetsFromEnv, appWritesGraphs, GRAPH_WRITER_ENV, graphWriterFromEnv, syncTargetsLine } from '../utils/graphTargets.js';
+import { AdminRequestError, assertReloadablePackages, AdminConflictError, registerAdminRoutes, resolveAdminSecret, } from '../utils/adminChannel.js';
 import { envMs, withTimeout } from '../utils/withTimeout.js';
 import { invalidateSourceUnder } from '../utils/reloadSource.js';
 import { installSpaFallback, repinSpaFallback, } from '../utils/spaFallback.js';
@@ -285,7 +286,7 @@ let LinkedServer = class LinkedServer extends Shape {
          * could not be loaded at all.
          */
         this.linkedPackageDirs = new Map();
-        /** The app's own workspace packages (`linkedPackage: true`), by real path. */
+        /** The app's own workspace packages (`linked.kind` of a package), by real path. */
         this.workspacePackageDirs = [];
         /** The names of the app's own workspace packages. */
         this.workspacePackageNames = new Set();
@@ -298,7 +299,7 @@ let LinkedServer = class LinkedServer extends Shape {
          * error is logged and contained.
          */
         this.booting = false;
-        /** Tail of the {@link resyncShapes} queue: one re-sync at a time. */
+        /** Tail of the graph content's queue: one request at a time. */
         this.shapeSyncQueue = Promise.resolve();
         /** Tail of the {@link onSourceChange} queue: reloads never interleave. */
         this.sourceReloadQueue = Promise.resolve();
@@ -364,19 +365,21 @@ let LinkedServer = class LinkedServer extends Shape {
         this.initPackage();
         this.server = express();
         await this.initBackendProviders();
-        this.warnOfSyncPins();
+        await this.logSyncTargets();
         await this.syncOntologiesOnBoot();
         await this.materializeShapesIntoStore();
         return this;
     }
     /**
      * Sync this server's registered shapes into app data, one named graph per package (see
-     * utils/syncShapes): each package's shapes in `{package IRI}/graph/shapes`, from its built
+     * utils/syncShapes) in every dataset the storage routing needs it in (core's
+     * `syncShapeGraphsRouted`; the default dataset when nothing is pinned, and a graph routing no
+     * longer sends to the default dataset is dropped there): each package's shapes in
+     * `{package IRI}/graph/shapes`, from its built
      * `shapes.ttl` (an installed package without one gets no shape graph), the app's own packages
      * generated in process in dev (through Vite's loader), and the app's generated single-owner
-     * shapes in `{DATA_ROOT}/graph/shapes`. Runs at boot, after the ontology sync, and again when
-     * the host asks for it over the control channel ({@link resyncShapes}). A source reload (HMR)
-     * does not sync shapes by itself.
+     * shapes in `{DATA_ROOT}/graph/shapes`. Runs at boot, after the ontology sync. A source reload
+     * (HMR) does not sync shapes.
      *
      * A graph whose stored content hash matches is not written, so a sync of unchanged shapes
      * writes nothing. Shapes an earlier sync wrote into the default graph are removed there once
@@ -386,10 +389,9 @@ let LinkedServer = class LinkedServer extends Shape {
      * Shape graphs of packages no longer registered stay unless the operator sets
      * `LINKED_SYNC_SHAPES_PRUNE_ORPHANS=true` — see `bootOrphanScope` in utils/syncShapes.
      *
-     * Opt-out via `linked.config` `syncShapesOnBoot` (default true); env
-     * LINKED_SYNC_SHAPES_ON_BOOT overrides for deployment. A host whose default
-     * dataset is a context router (one that can't write context-free) sets
-     * `syncShapesOnBoot: false` and syncs its shapes itself.
+     * Runs when {@link bootSyncs}: the app writes its own graphs and `linked.config` does not set
+     * `syncShapesOnBoot: false`. A host that writes the app's graphs (`LINKED_GRAPH_WRITER=host`)
+     * reads their content through `POST /admin/graph-content` ({@link graphContent}).
      */
     async materializeShapesIntoStore() {
         try {
@@ -399,22 +401,28 @@ let LinkedServer = class LinkedServer extends Shape {
             console.warn('[LinkedServer] shape sync failed (non-fatal):', err);
         }
     }
-    /** One shape sync into the default dataset; throws when it fails. */
+    /**
+     * Whether the boot syncs the shapes and the ontologies: the app writes its own graphs
+     * (`LINKED_GRAPH_WRITER` is `app`) and `linked.config` does not set `syncShapesOnBoot: false`.
+     */
+    bootSyncs() {
+        var _a;
+        return appWritesGraphs(process.env) && shapeSyncOn((_a = this.config) === null || _a === void 0 ? void 0 : _a.syncShapesOnBoot);
+    }
+    /** One shape sync, following the routing; throws when it fails in any dataset. */
     async syncRegisteredShapes() {
-        var _a, _b, _c, _d, _e;
-        if (!shapeSyncOn(process.env, (_a = this.config) === null || _a === void 0 ? void 0 : _a.syncShapesOnBoot)) {
-            return { written: 0, skipped: 'disabled' };
-        }
-        const appData = LinkedStorage.getDefaultDataset();
-        if (!appData)
-            return { written: 0, skipped: 'no-default-dataset' };
+        var _a, _b;
+        if (!this.bootSyncs())
+            return;
+        if (!LinkedStorage.getDefaultDataset())
+            return;
         const orphanScope = bootOrphanScope();
-        const appName = (_b = this.package) === null || _b === void 0 ? void 0 : _b.name;
-        const vite = (_c = this.config.server) === null || _c === void 0 ? void 0 : _c.vite;
+        const appName = (_a = this.package) === null || _a === void 0 ? void 0 : _a.name;
+        const vite = (_b = this.config.server) === null || _b === void 0 ? void 0 : _b.vite;
         const generate = viteShapesTurtleGenerator(vite);
-        // Explicit target: every registered shape goes into the app's own data store, regardless of
-        // per-shape routing or pins.
-        const shapeGraphs = await syncShapeGraphsInto(appData, {
+        // Follows the routing: each package's shape graph goes to every dataset its shapes (and the
+        // shape shapes) route to; the default dataset is one of them unless routing sends all elsewhere.
+        await syncRoutedShapeGraphs({
             core: await loadShapeGraphCore(),
             orphanScope,
             isOwn: (name) => name === appName || this.workspacePackageNames.has(name),
@@ -424,8 +432,6 @@ let LinkedServer = class LinkedServer extends Shape {
             appGraph: appShapesGraph(),
             appPackage: appName,
         });
-        const written = (_d = shapeGraphs.defaultGraph) !== null && _d !== void 0 ? _d : shapeGraphs.written.length + (((_e = shapeGraphs.appGraph) === null || _e === void 0 ? void 0 : _e.status) === 'written' ? 1 : 0);
-        return { written, orphanScope, shapeGraphs };
     }
     /** The root directory of a package with shapes: the app, a discovered linked package, or one the app resolves. */
     shapePackageDir(name) {
@@ -439,25 +445,34 @@ let LinkedServer = class LinkedServer extends Shape {
         return installed === null || installed === void 0 ? void 0 : installed.root;
     }
     /**
-     * Boot: one warning when routing pins the shape shapes or the ontology term shapes to a dataset
-     * other than the default one, since the syncs write into the default dataset only (see
-     * {@link syncPinWarning}).
+     * Boot: one line naming the datasets the boot syncs write into, when the routing sends any graph
+     * beyond the default dataset (see {@link syncTargetsLine}). Only for the syncs this boot runs.
      */
-    warnOfSyncPins() {
-        const warning = syncPinWarning();
-        if (warning)
-            console.warn(warning);
+    async logSyncTargets() {
+        if (!appWritesGraphs(process.env)) {
+            console.log(`[LinkedServer] ${GRAPH_WRITER_ENV}=host: the host writes this app's shape and ontology graphs; ` +
+                'the boot writes none (the host reads them through POST /admin/graph-content).');
+            return;
+        }
+        try {
+            const on = this.bootSyncs();
+            const line = syncTargetsLine({ shapeSync: on, ontologySync: on }, await import('@_linked/core/shapes/syncTargets'));
+            if (line)
+                console.log(line);
+        }
+        catch (err) {
+            console.warn('[LinkedServer] could not name the datasets the boot syncs write into:', err);
+        }
     }
     /**
      * Boot: sync the registered ontologies into their graphs in app data and run the shape
      * check, before the shape sync (see utils/ontologySync). The sync follows the shape sync's
-     * switch (`syncShapesOnBoot`, `LINKED_SYNC_SHAPES_ON_BOOT`), plus the opt-out
-     * `LINKED_SYNC_ONTOLOGIES_ON_BOOT=false`; the in-memory class hierarchy is loaded either way.
+     * switch ({@link bootSyncs}); the in-memory class hierarchy is loaded either way.
      * Never stops the boot: failures and findings are logged.
      */
     async syncOntologiesOnBoot() {
         try {
-            await runAsSystem(() => { var _a; return this.runOntologyPhase(bootSyncsOntologies(process.env, (_a = this.config) === null || _a === void 0 ? void 0 : _a.syncShapesOnBoot)); }, 'ontology sync at boot');
+            await runAsSystem(() => this.runOntologyPhase(this.bootSyncs()), 'ontology sync at boot');
         }
         catch (err) {
             console.warn('[LinkedServer] ontology sync failed (non-fatal):', err);
@@ -466,7 +481,7 @@ let LinkedServer = class LinkedServer extends Shape {
     /**
      * Every discovered linked package and every workspace package of the app registers its
      * ontologies (in dev, an unbuilt one through Vite), then the ontology sync (when
-     * `sync` is set) into the default dataset, then the shape check.
+     * `sync` is set), following the routing, then the shape check.
      * Orphaned ontology graphs (and earlier sync nodes) are pruned under the shape sync's orphan policy
      * (`LINKED_SYNC_SHAPES_PRUNE_ORPHANS`).
      */
@@ -475,6 +490,7 @@ let LinkedServer = class LinkedServer extends Shape {
         return runOntologyPhase(LinkedStorage.getDefaultDataset(), {
             core: await loadOntologyCore(),
             sync,
+            routed: true,
             orphanScope: bootOrphanScope(),
             dependencies: readDependencyLists((_a = this.linkedPackageDirs) !== null && _a !== void 0 ? _a : new Map(), this.package),
             packageDirs: ontologyPackageDirs(((_b = this.linkedPackageDirs) !== null && _b !== void 0 ? _b : new Map()).values(), (_c = this.workspacePackageDirs) !== null && _c !== void 0 ? _c : []),
@@ -482,58 +498,101 @@ let LinkedServer = class LinkedServer extends Shape {
         });
     }
     /**
-     * Re-sync the registered ontologies and shapes into app data, as the boot does,
-     * and report what was written: the ontology sync (every registered package,
-     * hash-skipped), the shape check's counts, then the shape sync. A failed ontology
-     * sync does not stop the shape sync; the run then fails with the ontology error. The host calls it (`POST /admin/sync-shapes`) after it
-     * changed the app's shape code, so the app — the only process that loads that
-     * code — writes its own shapes and their hashes.
+     * What the app's `'package'`-mode syncs would write, writing nothing (`POST /admin/graph-content`):
+     * per package its shape graph's Turtle and its ontology graph's N-Triples with the hash each
+     * record gets and its sources, and the app's own shape graph (`null` when it has no single-owner
+     * shapes; left out without `DATA_ROOT`). A host that writes the app's graphs itself
+     * (`LINKED_GRAPH_WRITER=host`) reads them here, after it changed the app's shape code: the app
+     * is the only process that loads that code.
      *
-     * `packages` names the packages whose source changed: the app itself or its
-     * direct dependencies, never `@_linked/*` ({@link assertReloadablePackages}). In
-     * dev (Vite) their modules are invalidated and their backends reloaded first
-     * ({@link onSourceChange}), so a shape added since the boot is registered before
-     * the sync; without Vite (a built app) nothing is reloaded. The answer names the
-     * packages reloaded and the node shapes registered after it, so the host can check
-     * that the shape it wrote is there. Runs as the system, never as the caller of a
-     * request, one at a time; a run that takes longer than
+     * `reload` names the packages whose source changed: the app itself or its direct dependencies
+     * (its `linked.unpublishedPackages` among them), never `@_linked/*`
+     * ({@link assertReloadablePackages}). In dev (Vite) their modules are invalidated and their
+     * backends reloaded first ({@link onSourceChange}), then the ontologies are registered again and
+     * the shape check runs, so a shape added since the boot is in the answer; without Vite (a built
+     * app) nothing is reloaded. `reloaded` names the packages reloaded. `packages` limits the
+     * answer. Each package's Turtle comes from where the shape sync takes it (an installed package
+     * without `shapes.ttl` has none: `withoutTurtle`).
+     * Refused with {@link AdminConflictError} unless both graph targets are `'package'`. Runs one at
+     * a time, as the system, never as the caller of a request; a run that takes longer than
      * `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120 s) fails and releases the queue.
      */
-    async resyncShapes({ packages = [] } = {}) {
-        assertReloadablePackages(packages, this.reloadablePackages());
-        const timeoutMs = envMs('LINKED_SHAPE_SYNC_TIMEOUT_MS', 120000);
-        const run = this.shapeSyncQueue.then(() => withTimeout(runAsSystem(async () => {
-            const reloaded = [];
-            for (const pkg of packages) {
-                if (await this.reloadPackageFromDisk(pkg))
-                    reloaded.push(pkg);
+    async graphContent({ packages, reload = [] } = {}) {
+        assertReloadablePackages(reload, this.reloadablePackages());
+        const graphTargets = getGraphTargets();
+        for (const [setting, env] of [['ontologyGraph', 'LINKED_ONTOLOGY_GRAPH'], ['shapeGraph', 'LINKED_SHAPE_GRAPH']]) {
+            if (graphTargets[setting] !== 'package') {
+                throw new AdminConflictError(`${setting} is ${JSON.stringify(graphTargets[setting])} (${env}); the graph content is what the 'package' mode writes, one graph per package`);
             }
-            const result = await syncOntologiesThenShapes(() => { var _a; return this.runOntologyPhase(shapeSyncOn(process.env, (_a = this.config) === null || _a === void 0 ? void 0 : _a.syncShapesOnBoot)); }, () => this.syncRegisteredShapes());
-            return { ...result, reloaded, shapes: [...getAllShapeClasses().keys()].sort() };
-        }, 'shape sync requested by the host'), timeoutMs, `the shape sync did not finish within ${timeoutMs} ms`));
+        }
+        return this.inShapeSyncQueue('the graph content', 'graph content requested by the host', async () => {
+            var _a, _b;
+            const reloaded = await this.reloadPackages(reload);
+            if (reloaded.length)
+                await this.runOntologyPhase(false);
+            const appName = (_a = this.package) === null || _a === void 0 ? void 0 : _a.name;
+            const generate = viteShapesTurtleGenerator((_b = this.config.server) === null || _b === void 0 ? void 0 : _b.vite);
+            const content = await graphContentOf({
+                core: await loadShapeGraphCore(),
+                isOwn: (name) => name === appName || this.workspacePackageNames.has(name),
+                dev: !!generate,
+                generate,
+                packageDirOf: (name) => this.shapePackageDir(name),
+                appGraph: appShapesGraph(),
+                ...(packages ? { packages } : {}),
+            });
+            return { graphTargets, ...content, reloaded };
+        });
+    }
+    /** Reload each of `packages` from disk (dev only); the ones actually reloaded. */
+    async reloadPackages(packages) {
+        const reloaded = [];
+        for (const pkg of packages) {
+            if (await this.reloadPackageFromDisk(pkg))
+                reloaded.push(pkg);
+        }
+        return reloaded;
+    }
+    /**
+     * Run `fn` in the graph content's queue (one at a time), as the system, failing it after
+     * `LINKED_SHAPE_SYNC_TIMEOUT_MS` (default 120 s) and releasing the queue.
+     */
+    inShapeSyncQueue(what, why, fn) {
+        const timeoutMs = envMs('LINKED_SHAPE_SYNC_TIMEOUT_MS', 120000);
+        const run = this.shapeSyncQueue.then(() => withTimeout(runAsSystem(fn, why), timeoutMs, `${what} did not finish within ${timeoutMs} ms`));
         this.shapeSyncQueue = run.catch(() => undefined);
         return run;
     }
-    /** The packages a host may ask to reload: the app itself and its direct dependencies. */
+    /**
+     * The packages a host may ask to reload: the app itself and its direct dependencies, which
+     * include every package in its `linked.unpublishedPackages`, transitively
+     * ({@link listedPackageNames}). Read from disk on each call: a list written after the boot
+     * counts. A malformed list throws.
+     */
     reloadablePackages() {
         var _a, _b;
         const names = new Set();
         if ((_a = this.package) === null || _a === void 0 ? void 0 : _a.name)
             names.add(this.package.name);
+        let json;
         try {
-            const json = JSON.parse(fsNative.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
-            if (json.name)
-                names.add(json.name);
-            for (const field of ['dependencies', 'devDependencies']) {
-                for (const name of Object.keys((_b = json[field]) !== null && _b !== void 0 ? _b : {}))
-                    names.add(name);
-            }
+            json = JSON.parse(fsNative.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+        }
+        catch (_c) {
+            return names;
         }
-        catch (_c) { }
+        if (json.name)
+            names.add(json.name);
+        for (const field of ['dependencies', 'devDependencies']) {
+            for (const name of Object.keys((_b = json[field]) !== null && _b !== void 0 ? _b : {}))
+                names.add(name);
+        }
+        for (const name of listedPackageNames(process.cwd(), json))
+            names.add(name);
         return names;
     }
     /**
-     * Re-read one package's source from disk (dev only); see {@link resyncShapes}.
+     * Re-read one package's source from disk (dev only); see {@link graphContent}.
      * Resolves whether it reloaded anything.
      */
     async reloadPackageFromDisk(pkg) {
@@ -695,7 +754,7 @@ let LinkedServer = class LinkedServer extends Shape {
         // });
         // before controllers
         await this.initBackendProviders();
-        this.warnOfSyncPins();
+        await this.logSyncTargets();
         await this.syncOntologiesOnBoot();
         await this.materializeShapesIntoStore();
         //START OF EXPRESS ROUTES AND MIDDLEWARE
@@ -769,7 +828,7 @@ let LinkedServer = class LinkedServer extends Shape {
         registerAdminRoutes(this.server, resolveAdminSecret(), {
             // The host's provisioner starts the app again after it exits.
             exit: () => process.exit(0),
-            syncShapes: (request) => this.resyncShapes(request),
+            graphContent: (request) => this.graphContent(request),
         });
         // after controller
         await this.callGenericBackendProvidersMethod('setupAfterControllers');
@@ -823,8 +882,10 @@ let LinkedServer = class LinkedServer extends Shape {
         // LINKED_ONTOLOGY_GRAPH / LINKED_SHAPE_GRAPH: checked (an invalid value stops the boot) and set
         // once as core's global graph targets, before any store is initialised and before the syncs.
         // A rejected boot does not end the process by itself, so the error is fatal.
+        // LINKED_GRAPH_WRITER: checked here too, so an invalid value stops the boot before anything runs.
         try {
             applyGraphTargetsFromEnv(process.env);
+            graphWriterFromEnv(process.env);
         }
         catch (err) {
             throw new FatalStartupError(`[LinkedServer] ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`, { cause: err });
@@ -1047,18 +1108,21 @@ let LinkedServer = class LinkedServer extends Shape {
     }
     /**
      * Filters local workspace packages to only those reachable from the app's
-     * dependency tree. Mirrors the logic used by `buildAll` in lincd-cli.
+     * dependency tree: `dependencies` and `linked.unpublishedPackages`, of the app
+     * and of each package reached. Mirrors the logic used by `buildAll` in the cli.
      */
     filterPackagesByDependencyTree(allPackages, appPackageJson) {
+        var _a, _b;
         const relevantPackages = new Map();
         const packagesToCheck = new Set();
         const processedPackages = new Set();
-        // Start with direct dependencies from the app
-        if (appPackageJson.dependencies) {
-            for (const dep of Object.keys(appPackageJson.dependencies)) {
-                if (allPackages.has(dep)) {
-                    packagesToCheck.add(dep);
-                }
+        // Start with direct dependencies from the app, its linked.unpublishedPackages among them
+        for (const dep of [
+            ...Object.keys((_a = appPackageJson.dependencies) !== null && _a !== void 0 ? _a : {}),
+            ...unpublishedNames(appPackageJson),
+        ]) {
+            if (allPackages.has(dep)) {
+                packagesToCheck.add(dep);
             }
         }
         // Recursively follow each package's dependencies
@@ -1073,11 +1137,12 @@ let LinkedServer = class LinkedServer extends Shape {
             if (packageDetails) {
                 relevantPackages.set(packageName, packageDetails);
                 const pkg = getPackageJSON(packageDetails.path);
-                if (pkg === null || pkg === void 0 ? void 0 : pkg.dependencies) {
-                    for (const dep of Object.keys(pkg.dependencies)) {
-                        if (allPackages.has(dep) && !processedPackages.has(dep)) {
-                            packagesToCheck.add(dep);
-                        }
+                for (const dep of [
+                    ...Object.keys((_b = pkg === null || pkg === void 0 ? void 0 : pkg.dependencies) !== null && _b !== void 0 ? _b : {}),
+                    ...unpublishedNames(pkg),
+                ]) {
+                    if (allPackages.has(dep) && !processedPackages.has(dep)) {
+                        packagesToCheck.add(dep);
                     }
                 }
             }
@@ -1538,7 +1603,7 @@ let LinkedServer = class LinkedServer extends Shape {
      * Reload one package's backend providers from source.
      *
      * Called by the CLI orchestrator's Vite watcher whenever a `.ts`/`.tsx`
-     * file inside a workspace package changes, and by {@link resyncShapes}.
+     * file inside a workspace package changes, and by {@link graphContent}.
      * Disposes the package's existing providers (so routes, listeners, timers
      * don't accumulate), drops them from the registry, and re-runs
      * indexPackageBackendProviders to pick up the freshly-imported module.