@_linked/core 2.19.0 → 2.20.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 2.20.1
+
+### Patch Changes
+
+- [#235](https://github.com/linked-fw/core/pull/235) [`19624f7`](https://github.com/linked-fw/core/commit/19624f7bb7b1d83bd99d9797a7da41fe7e09432b) Thanks [@flyon](https://github.com/flyon)! - Point `repository.url` at the linked-fw organisation, so npm provenance verification matches the repository that builds the package.
+
+## 2.20.0
+
+### Minor Changes
+
+- [#230](https://github.com/linked-fw/core/pull/230) [`bf8df0c`](https://github.com/linked-fw/core/commit/bf8df0c043cdb588e4b9f8baf97f87b340f0078b) Thanks [@flyon](https://github.com/flyon)! - Purpose-named file stores, save options and `statFile`.
+
+  - `LinkedFileStorage` gains a purpose registry: `registerPurpose`, `setStore`,
+    `getStore`, `hasStore`, `listPurposes` and `accessURLFor`. `getStore(purpose)`
+    returns the store configured for that purpose; a purpose that is registered
+    but not configured falls back to the default store (noted once with
+    `console.debug`); an unregistered
+    purpose throws, listing the known purposes, so a typo cannot silently write to
+    the wrong store. The well-known purposes `uploads` and `appAssets` are exported
+    as `FileStorePurposes` and registered at module load. `uploads` is an ordinary
+    purpose: `setDefaultStore` configures no purpose of its own, so `uploads`
+    resolves to the default store as a fallback, `hasStore('uploads')` is true only
+    after an explicit `setStore('uploads', store)`, and that call has the same
+    effect whether it runs before or after `setDefaultStore`.
+  - `getDefaultDataset`/`setDefaultDataset` are renamed to
+    `getDefaultStore`/`setDefaultStore`. The old names remain as `@deprecated`
+    aliases that forward, so no caller has to change; they will be dropped in the
+    next major.
+  - `IFileStore.saveFile` now takes `SaveFileOptions` (`mimeType`, `cacheControl`,
+    `metadata`, `preventDuplicates`) as its third argument, still accepting a
+    `string` there as the old positional `mimeType`. `normalizeSaveFileOptions` is
+    exported for implementations; it reports `preventDuplicates` as `undefined`
+    when the caller did not specify one — there is no core-wide default, so each
+    store keeps applying its own (`S3FileStore` overwrites, `LocalFileStore` adds a
+    random suffix). `options.preventDuplicates` wins over the positional argument.
+    `LinkedFileStorage.saveFile` likewise forwards an unspecified
+    `preventDuplicates` as `undefined` rather than `false`, so a
+    `saveFile(path, bytes)` call keeps behaving exactly as before.
+  - `IFileStore` gains an optional `statFile(filePath): Promise<FileStat | null>`
+    for verify-after-upload. Existing implementations stay valid.
+
+## 2.19.1
+
+### Patch Changes
+
+- [#231](https://github.com/linked-fw/core/pull/231) [`58a5b7a`](https://github.com/linked-fw/core/commit/58a5b7af7332584e9f40c16d17e303f18d86962a) Thanks [@flyon](https://github.com/flyon)! - Declare npm as the package manager for this repo and mark `package-lock.json` as a generated file.
+
 ## 2.19.0
 
 ### Minor Changes

package/README.md

@@ -362,6 +362,86 @@ LinkedStorage.setDefaultDataset(stores.appData);
 
 Each store class must accept a single config-object argument (`new StoreClass(config)`). `@_linked/fuseki`'s `FusekiStore` and `@_linked/server`'s `BackendAPIStore` both follow this contract.
 
+## File storage
+
+`LinkedStorage` routes *quads*; `LinkedFileStorage` routes *files*. Files are addressed by **purpose** — a short string naming what the files are for (`uploads`, `appAssets`, …) — so an app can send release bundles to a CDN bucket and user uploads to another store without any caller knowing which.
+
+```ts
+import {LinkedFileStorage, FileStorePurposes} from '@_linked/core';
+import {S3FileStore} from '@_linked/s3';
+
+LinkedFileStorage.setDefaultStore(new S3FileStore({/* … */}));           // fallback for every purpose
+LinkedFileStorage.setStore(FileStorePurposes.appAssets, new S3FileStore({/* cdn */}));
+
+await LinkedFileStorage.getStore(FileStorePurposes.appAssets).saveFile('/app.js', bytes);
+LinkedFileStorage.accessURLFor(FileStorePurposes.appAssets); // → https://cdn.example.com
+```
+
+### Resolution rule
+
+`getStore(purpose)` resolves in one order, and there is no fourth case:
+
+1. **configured** — a store was passed to `setStore(purpose, store)` → that store;
+2. **registered but not configured** → the default store, with a one-time `console.debug` line saying the purpose has no dedicated store (the normal case for a single-store app; it throws instead if no default store is set);
+3. **not registered** → throws, listing the known purposes. A typo like `'appAsset'` must not silently write release bundles into the uploads store.
+
+`uploads` is an ordinary purpose with no special case: `setDefaultStore` configures *no* purpose, so `uploads` reaches the default store through the fallback in step 2, and `setStore('uploads', other)` wins whether it is called before or after `setDefaultStore`.
+
+| Method | Meaning |
+| --- | --- |
+| `registerPurpose(purpose, {description?})` | Declare a purpose without configuring a store. |
+| `setStore(purpose, store)` | Configure (and register) the store; calls `store.init()`. |
+| `getStore(purpose)` | Resolve per the rule above. A **live reference** — call it per operation if config can change. |
+| `hasStore(purpose)` | Whether a store was *explicitly configured*. Ignores the fallback, so it is `false` while `getStore` still works. Never use it as a guard before `getStore`. |
+| `listPurposes()` | `{purpose, description?, configured}` for every declared purpose. |
+| `accessURLFor(purpose)` | The `accessURL` of the resolved store. |
+| `getDefaultStore()` / `setDefaultStore(store)` | The fallback store. `getDefaultDataset`/`setDefaultDataset` are `@deprecated` aliases that forward, kept until the next major. |
+
+### Introducing a purpose from a package
+
+Export the constant and register it **in the same module**, so importing the constant *is* the registration and load order resolves itself:
+
+```ts
+// @_linked/captures/purposes.ts
+import {LinkedFileStorage} from '@_linked/core';
+
+export const CapturesPurpose = 'captures';
+LinkedFileStorage.registerPurpose(CapturesPurpose, {description: '3D capture artifacts.'});
+```
+
+A consumer that imports `CapturesPurpose` can call `getStore(CapturesPurpose)` immediately; an app that never splits it out simply gets the default store. Core ships only `FileStorePurposes.uploads` and `FileStorePurposes.appAssets` — a new purpose belongs in the package that owns the concept.
+
+### Saving files: `SaveFileOptions`
+
+```ts
+await store.saveFile('/app.js', bytes, {
+  mimeType: 'application/javascript',
+  cacheControl: 'public, max-age=31536000, immutable',
+  metadata: {release: '1.2.3'},
+  preventDuplicates: true, // rename instead of overwriting when the path is taken
+});
+
+// Backwards compatible: a string third argument is read as the positional mimeType.
+await store.saveFile('/photo.webp', bytes, 'image/webp', true);
+```
+
+`options.preventDuplicates` wins over the positional fourth argument. Implementations should start with `normalizeSaveFileOptions(options, preventDuplicates)`, which collapses both forms into one object.
+
+> **There is no core-wide `preventDuplicates` default.** When a caller does not specify one it stays `undefined` all the way to the store, and **each store applies its own**: `LocalFileStore` adds a random suffix, `S3FileStore` overwrites. Pass it explicitly whenever the behaviour matters — never assume a default.
+
+### Optional `statFile`
+
+```ts
+const stat = await store.statFile?.('/app.js'); // FileStat | null | undefined
+if (!stat) {
+  // Store cannot report metadata, or the file is absent — skip verification.
+} else if (stat.sha256) {
+  // Only a real content hash verifies. `etag` is not one on S3.
+}
+```
+
+`statFile` is optional by design: a store without it still publishes. A caller must treat a missing method (`undefined`) or a missing `sha256` as "cannot verify" and continue, rather than failing the upload or falling back to `etag`.
+
 ## Automatic data validation
 
 SHACL shapes are ideal for data validation. Linked generates SHACL shapes from your TypeScript Shape classes, which you can sync to your store for schema-level validation. When your store enforces those shapes at runtime, you get both schema validation and runtime enforcement for extra safety.

package/lib/esm/interfaces/IFileStore.d.ts

@@ -1,4 +1,38 @@
 import type { Readable } from 'stream';
+/**
+ * Options for `IFileStore.saveFile`.
+ *
+ * Passed as the third argument. A plain `string` is still accepted there and is
+ * read as the old positional `mimeType`, so existing callers keep working.
+ */
+export interface SaveFileOptions {
+    /** Content type of the stored bytes, e.g. `image/webp`. */
+    mimeType?: string;
+    /** Cache header the store should attach, e.g. `public, max-age=31536000, immutable`. */
+    cacheControl?: string;
+    /** Store-level user metadata, when the backing store supports it. */
+    metadata?: Record<string, string>;
+    /**
+     * Rename instead of overwriting when the path is already taken.
+     *
+     * Left `undefined` when the caller did not say: each store then applies its
+     * own default (`S3FileStore` overwrites, `LocalFileStore` adds a suffix).
+     */
+    preventDuplicates?: boolean;
+}
+/**
+ * Metadata of a stored file, for verify-after-upload.
+ *
+ * `sha256` is only set when the store can actually report a content hash; a
+ * caller that does not get one must treat the file as "cannot verify" rather
+ * than falling back to `etag`, which is not a content hash on S3.
+ */
+export interface FileStat {
+    size: number;
+    /** Only when the store can report it. */
+    sha256?: string;
+    etag?: string;
+}
 export interface IFileStore {
     /**
      * The base URL to access the filestore's files. For example:
@@ -12,5 +46,34 @@ export interface IFileStore {
     fileExists(filePath: string): Promise<boolean>;
     getFile(filePath: string): Promise<Buffer | null>;
     listFiles(prefix?: string): Promise<string[]>;
-    saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, mimeType?: string, preventDuplicates?: boolean): Promise<string | null>;
+    saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, 
+    /** `SaveFileOptions`, or a `string` read as the old positional `mimeType`. */
+    options?: SaveFileOptions | string, 
+    /** Only honoured when `options` is a string; otherwise use `options.preventDuplicates`. */
+    preventDuplicates?: boolean): Promise<string | null>;
+    /**
+     * Optional. Metadata of a stored file, for verify-after-upload.
+     * Resolves to `null` when the file does not exist.
+     *
+     * Optional by design (plan 011 D7): a store without it still publishes, and
+     * the caller simply skips verification.
+     */
+    statFile?(filePath: string): Promise<FileStat | null>;
 }
+/**
+ * Normalise `saveFile`'s widened third argument into a single options object.
+ * Every `IFileStore` implementation should call this first, so the positional
+ * mime-type form and the options form cannot drift apart.
+ *
+ * `preventDuplicates` stays `undefined` when neither `options.preventDuplicates`
+ * nor the positional argument was given: "unspecified" travels end to end and
+ * **each store applies its own default** (`S3FileStore` overwrites,
+ * `LocalFileStore` adds a random suffix). This helper must never invent `false`,
+ * or a two-argument `saveFile(path, bytes)` would silently start overwriting.
+ *
+ * `options.preventDuplicates` wins over the positional argument when both are
+ * given.
+ */
+export declare function normalizeSaveFileOptions(options?: SaveFileOptions | string, preventDuplicates?: boolean): SaveFileOptions & {
+    preventDuplicates?: boolean | undefined;
+};

package/lib/esm/interfaces/IFileStore.js

@@ -1,2 +1,22 @@
-export {};
+/**
+ * Normalise `saveFile`'s widened third argument into a single options object.
+ * Every `IFileStore` implementation should call this first, so the positional
+ * mime-type form and the options form cannot drift apart.
+ *
+ * `preventDuplicates` stays `undefined` when neither `options.preventDuplicates`
+ * nor the positional argument was given: "unspecified" travels end to end and
+ * **each store applies its own default** (`S3FileStore` overwrites,
+ * `LocalFileStore` adds a random suffix). This helper must never invent `false`,
+ * or a two-argument `saveFile(path, bytes)` would silently start overwriting.
+ *
+ * `options.preventDuplicates` wins over the positional argument when both are
+ * given.
+ */
+export function normalizeSaveFileOptions(options, preventDuplicates) {
+    var _a;
+    if (typeof options === 'string') {
+        return { mimeType: options, preventDuplicates };
+    }
+    return Object.assign(Object.assign({}, (options !== null && options !== void 0 ? options : {})), { preventDuplicates: (_a = options === null || options === void 0 ? void 0 : options.preventDuplicates) !== null && _a !== void 0 ? _a : preventDuplicates });
+}
 //# sourceMappingURL=IFileStore.js.map

package/lib/esm/interfaces/IFileStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFileStore.js","sourceRoot":"","sources":["../../../src/interfaces/IFileStore.ts"],"names":[],"mappings":""}
+{"version":3,"file":"IFileStore.js","sourceRoot":"","sources":["../../../src/interfaces/IFileStore.ts"],"names":[],"mappings":"AA4EA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAkC,EAClC,iBAA2B;;IAE3B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,EAAC,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAC,CAAC;IAChD,CAAC;IACD,uCACK,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC,KAClB,iBAAiB,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,iBAAiB,mCAAI,iBAAiB,IAClE;AACJ,CAAC"}

package/lib/esm/utils/LinkedFileStorage.d.ts

@@ -1,17 +1,110 @@
-import type { IFileStore } from '../interfaces/IFileStore.js';
+import type { IFileStore, SaveFileOptions } from '../interfaces/IFileStore.js';
 import type { Readable } from 'stream';
+/**
+ * Well-known file store purposes shipped with core.
+ *
+ * Core itself never writes to `appAssets`; it lives here as the documented
+ * convention (plan 011 D4) so the CLI and apps agree on the same key without a
+ * shared runtime dependency. Any *new* purpose's constant belongs in the
+ * runtime package that owns the concept, not here and not in the CLI.
+ */
+export declare const FileStorePurposes: {
+    /** User-generated files. Resolves to the default store unless split out. */
+    readonly uploads: "uploads";
+    /** Built app bundles published by `linked build-app`. */
+    readonly appAssets: "appAssets";
+};
+export type FileStorePurpose = (typeof FileStorePurposes)[keyof typeof FileStorePurposes];
+export interface FileStorePurposeInfo {
+    description?: string;
+}
+export interface FileStorePurposeListing {
+    purpose: string;
+    description?: string;
+    configured: boolean;
+}
 export declare abstract class LinkedFileStorage {
-    private static defaultDataset;
+    private static defaultStore;
     private static url;
+    /** Purpose → the store configured for it. */
+    private static stores;
+    /** Every declared purpose, configured or not. */
+    private static purposes;
+    /** Purposes already reported as falling back, so the log fires once each. */
+    private static loggedFallbacks;
     static get accessURL(): string;
     static setDefaultAccessURL(accessURL: string): string;
+    static getDefaultStore(): IFileStore;
+    /**
+     * Configure the default store: the fallback for *every* purpose, `uploads`
+     * included.
+     *
+     * It deliberately writes no entry into the purpose → store map, so `uploads`
+     * behaves exactly like `appAssets`: an explicit `setStore('uploads', other)`
+     * wins whenever it is called, before or after this, and `hasStore('uploads')`
+     * stays false until such a call is made.
+     */
+    static setDefaultStore(store: IFileStore): void;
+    /** @deprecated use {@link LinkedFileStorage.getDefaultStore} */
     static getDefaultDataset(): IFileStore;
+    /** @deprecated use {@link LinkedFileStorage.setDefaultStore} */
     static setDefaultDataset(dataset: IFileStore): void;
+    /**
+     * Declare a purpose without configuring a store for it.
+     *
+     * A package that *reads* a purpose the app may leave unconfigured registers
+     * it in the same module that exports its constant, so importing the constant
+     * is the registration and ordering resolves itself.
+     */
+    static registerPurpose(purpose: string, info?: FileStorePurposeInfo): void;
+    /** Configure the store for a purpose. Also registers the purpose. */
+    static setStore(purpose: string, store: IFileStore): void;
+    /**
+     * Resolve the store for a purpose (plan 011 D2):
+     * - configured        → that store;
+     * - registered, not configured → the default store, logged once;
+     * - not registered    → throws.
+     *
+     * Unregistered throws on purpose: only a registry can tell "the app did not
+     * split this purpose out" apart from a typo. Without it, `'appAsset'` would
+     * silently write release bundles into the uploads store.
+     *
+     * The returned store is a **live reference**, resolved once at call time. A
+     * caller that holds on to a store returned through the default-store fallback
+     * keeps that object even after a later `setStore(purpose, other)`; call
+     * `getStore` again per operation if the configuration can change at runtime.
+     */
+    static getStore(purpose: string): IFileStore;
+    /**
+     * Whether a store was *explicitly configured* for this purpose.
+     *
+     * The default-store fallback is deliberately ignored: `hasStore(p)` is false
+     * while `getStore(p)` still returns a usable store via the default. Use this
+     * to ask "did the app split this purpose out?", never as a guard before
+     * `getStore` — that would skip a perfectly working fallback.
+     */
+    static hasStore(purpose: string): boolean;
+    /** Every declared purpose, with whether it has its own store. */
+    static listPurposes(): FileStorePurposeListing[];
+    /** The access URL of the store resolved for this purpose. */
+    static accessURLFor(purpose: string): string;
     static deleteFile(filePath: string): Promise<void>;
     static fileExists(filePath: string): Promise<boolean>;
     static getFile(filePath: string): Promise<Buffer>;
     static listFiles(prefix?: string): Promise<string[]>;
-    static saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, mimeType?: string, preventDuplicates?: boolean): Promise<string>;
+    static saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, options?: SaveFileOptions | string, 
+    /**
+     * Forwarded exactly as given. No default here on purpose: "unspecified"
+     * must reach the store so it can apply its own default.
+     */
+    preventDuplicates?: boolean): Promise<string>;
+    /**
+     * Clears the module-global registry and default store.
+     * For tests only — the registry is process-wide state.
+     *
+     * @internal
+     */
+    static resetForTests(): void;
 }
 /**
  * Get the full path of an asset based on the way LinkedFileStorage is configured

package/lib/esm/utils/LinkedFileStorage.js

@@ -1,39 +1,191 @@
+/**
+ * Well-known file store purposes shipped with core.
+ *
+ * Core itself never writes to `appAssets`; it lives here as the documented
+ * convention (plan 011 D4) so the CLI and apps agree on the same key without a
+ * shared runtime dependency. Any *new* purpose's constant belongs in the
+ * runtime package that owns the concept, not here and not in the CLI.
+ */
+export const FileStorePurposes = {
+    /** User-generated files. Resolves to the default store unless split out. */
+    uploads: 'uploads',
+    /** Built app bundles published by `linked build-app`. */
+    appAssets: 'appAssets',
+};
 export class LinkedFileStorage {
     static get accessURL() {
         // check if default store is not set, return default accessURL
-        if (!this.defaultDataset) {
+        if (!this.defaultStore) {
             return this.url;
         }
-        return this.defaultDataset.accessURL;
+        return this.defaultStore.accessURL;
     }
     static setDefaultAccessURL(accessURL) {
         return (this.url = accessURL);
     }
+    static getDefaultStore() {
+        return this.defaultStore;
+    }
+    /**
+     * Configure the default store: the fallback for *every* purpose, `uploads`
+     * included.
+     *
+     * It deliberately writes no entry into the purpose → store map, so `uploads`
+     * behaves exactly like `appAssets`: an explicit `setStore('uploads', other)`
+     * wins whenever it is called, before or after this, and `hasStore('uploads')`
+     * stays false until such a call is made.
+     */
+    static setDefaultStore(store) {
+        this.defaultStore = store;
+        if (this.defaultStore.init) {
+            this.defaultStore.init();
+        }
+    }
+    /** @deprecated use {@link LinkedFileStorage.getDefaultStore} */
     static getDefaultDataset() {
-        return this.defaultDataset;
+        return this.getDefaultStore();
     }
+    /** @deprecated use {@link LinkedFileStorage.setDefaultStore} */
     static setDefaultDataset(dataset) {
-        this.defaultDataset = dataset;
-        if (this.defaultDataset.init) {
-            this.defaultDataset.init();
+        this.setDefaultStore(dataset);
+    }
+    /**
+     * Declare a purpose without configuring a store for it.
+     *
+     * A package that *reads* a purpose the app may leave unconfigured registers
+     * it in the same module that exports its constant, so importing the constant
+     * is the registration and ordering resolves itself.
+     */
+    static registerPurpose(purpose, info = {}) {
+        var _a;
+        const existing = this.purposes.get(purpose);
+        // Keep an existing description rather than blanking it on a re-register.
+        this.purposes.set(purpose, {
+            description: (_a = info.description) !== null && _a !== void 0 ? _a : existing === null || existing === void 0 ? void 0 : existing.description,
+        });
+    }
+    /** Configure the store for a purpose. Also registers the purpose. */
+    static setStore(purpose, store) {
+        this.registerPurpose(purpose);
+        this.stores.set(purpose, store);
+        if (store.init) {
+            store.init();
         }
     }
+    /**
+     * Resolve the store for a purpose (plan 011 D2):
+     * - configured        → that store;
+     * - registered, not configured → the default store, logged once;
+     * - not registered    → throws.
+     *
+     * Unregistered throws on purpose: only a registry can tell "the app did not
+     * split this purpose out" apart from a typo. Without it, `'appAsset'` would
+     * silently write release bundles into the uploads store.
+     *
+     * The returned store is a **live reference**, resolved once at call time. A
+     * caller that holds on to a store returned through the default-store fallback
+     * keeps that object even after a later `setStore(purpose, other)`; call
+     * `getStore` again per operation if the configuration can change at runtime.
+     */
+    static getStore(purpose) {
+        const configured = this.stores.get(purpose);
+        if (configured) {
+            return configured;
+        }
+        if (!this.purposes.has(purpose)) {
+            throw new Error(`Unknown file store purpose '${purpose}'. Register it with LinkedFileStorage.setStore(), ` +
+                `or import the package that defines it. Known purposes: ${this.listPurposes()
+                    .map((entry) => entry.purpose)
+                    .join(', ') || '(none)'}`);
+        }
+        if (!this.defaultStore) {
+            throw new Error(`No file store is configured for purpose '${purpose}', and no default store is configured. ` +
+                `Call LinkedFileStorage.setStore('${purpose}', store) or LinkedFileStorage.setDefaultStore(store).`);
+        }
+        if (!this.loggedFallbacks.has(purpose)) {
+            this.loggedFallbacks.add(purpose);
+            // `debug`, not `info`: falling back is the normal configuration for an
+            // app that runs one store, so this must not read as a problem or show up
+            // in default-level logs. It stays available when diagnosing which store a
+            // purpose actually resolved to.
+            console.debug(`[LinkedFileStorage] Purpose '${purpose}' has no dedicated store; using the default store.`);
+        }
+        return this.defaultStore;
+    }
+    /**
+     * Whether a store was *explicitly configured* for this purpose.
+     *
+     * The default-store fallback is deliberately ignored: `hasStore(p)` is false
+     * while `getStore(p)` still returns a usable store via the default. Use this
+     * to ask "did the app split this purpose out?", never as a guard before
+     * `getStore` — that would skip a perfectly working fallback.
+     */
+    static hasStore(purpose) {
+        return this.stores.has(purpose);
+    }
+    /** Every declared purpose, with whether it has its own store. */
+    static listPurposes() {
+        return Array.from(this.purposes.entries()).map(([purpose, info]) => ({
+            purpose,
+            description: info.description,
+            configured: this.stores.has(purpose),
+        }));
+    }
+    /** The access URL of the store resolved for this purpose. */
+    static accessURLFor(purpose) {
+        return this.getStore(purpose).accessURL;
+    }
     static deleteFile(filePath) {
-        return this.defaultDataset.deleteFile(filePath);
+        return this.defaultStore.deleteFile(filePath);
     }
     static fileExists(filePath) {
-        return this.defaultDataset.fileExists(filePath);
+        return this.defaultStore.fileExists(filePath);
     }
     static getFile(filePath) {
-        return this.defaultDataset.getFile(filePath);
+        return this.defaultStore.getFile(filePath);
     }
     static listFiles(prefix) {
-        return this.defaultDataset.listFiles(prefix);
+        return this.defaultStore.listFiles(prefix);
     }
-    static saveFile(filePath, fileContent, mimeType, preventDuplicates = false) {
-        return this.defaultDataset.saveFile(filePath, fileContent, mimeType, preventDuplicates);
+    static saveFile(filePath, fileContent, options, 
+    /**
+     * Forwarded exactly as given. No default here on purpose: "unspecified"
+     * must reach the store so it can apply its own default.
+     */
+    preventDuplicates) {
+        return this.defaultStore.saveFile(filePath, fileContent, options, preventDuplicates);
     }
+    /**
+     * Clears the module-global registry and default store.
+     * For tests only — the registry is process-wide state.
+     *
+     * @internal
+     */
+    static resetForTests() {
+        this.stores.clear();
+        this.purposes.clear();
+        this.loggedFallbacks.clear();
+        this.defaultStore = undefined;
+        this.url = undefined;
+        registerWellKnownPurposes();
+    }
+}
+/** Purpose → the store configured for it. */
+LinkedFileStorage.stores = new Map();
+/** Every declared purpose, configured or not. */
+LinkedFileStorage.purposes = new Map();
+/** Purposes already reported as falling back, so the log fires once each. */
+LinkedFileStorage.loggedFallbacks = new Set();
+/** The purposes core ships with are declared at module load. */
+function registerWellKnownPurposes() {
+    LinkedFileStorage.registerPurpose(FileStorePurposes.uploads, {
+        description: 'User-generated files. Falls back to the default store.',
+    });
+    LinkedFileStorage.registerPurpose(FileStorePurposes.appAssets, {
+        description: 'Built app bundles published by `linked build-app`.',
+    });
 }
+registerWellKnownPurposes();
 /**
  * Get the full path of an asset based on the way LinkedFileStorage is configured
  * Returns accessURL + directory (/public by default) + path

package/lib/esm/utils/LinkedFileStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"LinkedFileStorage.js","sourceRoot":"","sources":["../../../src/utils/LinkedFileStorage.ts"],"names":[],"mappings":"AAGA,MAAM,OAAgB,iBAAiB;IAIrC,MAAM,KAAK,SAAS;QAClB,8DAA8D;QAC9D,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,GAAG,CAAC;QAClB,CAAC;QAED,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,mBAAmB,CAAC,SAAiB;QAC1C,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,iBAAiB;QACtB,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,OAAmB;QAC1C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAE9B,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,QAAgB;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,QAAgB;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,QAAgB;QAC7B,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,MAAe;QAC9B,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,QAAQ,CACb,QAAgB,EAChB,WAAoD,EACpD,QAAiB,EACjB,oBAA6B,KAAK;QAElC,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,CACjC,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,iBAAiB,CAClB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,YAAoB,SAAS;IAC/D,2EAA2E;IAC3E,sEAAsE;IACtE,wEAAwE;IACxE,0EAA0E;IAC1E,6CAA6C;IAC7C,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,iBAAiB,CAAC,SAAS,CAAC;IAC9C,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC;IAC9C,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"LinkedFileStorage.js","sourceRoot":"","sources":["../../../src/utils/LinkedFileStorage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@_linked/core",
-  "version": "2.19.0",
+  "version": "2.20.1",
+  "packageManager": "npm@11.19.1",
   "license": "MIT",
   "linkedPackage": true,
   "type": "module",
   "description": "Linked.js core query and SHACL shape DSL (copy-then-prune baseline)",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/linked-cm/core.git"
+    "url": "git+https://github.com/linked-fw/core.git"
   },
   "main": "lib/esm/index.js",
   "module": "lib/esm/index.js",