fundus 0.14.0 → 0.16.0

package/dist/server/check.d.ts

@@ -1,10 +1,10 @@
-import { type Library, type ValidationIssueDto } from '../core/index.js';
+import { type EffectiveLibrary, type Library, type LibraryMembership, type MergeProvenance, type ValidationIssueDto } from '../core/index.js';
 import { type RawClassification } from './raw-reconciliation.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 /** One machine-readable check finding (the `--json` failure-list shape, M9). */
 export interface CheckFinding {
     /** The failure category. */
-    kind: 'validation' | 'proxy-missing' | 'proxy-unresolvable' | 'proxy-orphaned' | 'module-missing' | 'module-out-of-sync' | 'module-stray' | 'module-regeneration-failed' | 'unreachable-asset' | 'potential-image-duplicate' | 'raw-hash-drift' | 'raw-type-incompatible' | 'raw-scan-incomplete' | 'raw-unmanaged';
+    kind: 'validation' | 'proxy-missing' | 'proxy-unresolvable' | 'proxy-orphaned' | 'module-missing' | 'module-out-of-sync' | 'module-stray' | 'module-regeneration-failed' | 'unreachable-asset' | 'potential-image-duplicate' | 'raw-hash-drift' | 'raw-type-incompatible' | 'raw-scan-incomplete' | 'raw-unmanaged' | 'slot-unfilled' | 'slot-unmaterialized' | 'package-conflict' | 'package-type-mismatch';
     message: string;
     /** The asset the finding concerns, where applicable. */
     assetId?: string;
@@ -26,9 +26,19 @@ export interface CheckReport {
     manifestCount: number;
 }
 export interface CheckAdvisory {
-    kind: 'usage-not-configured';
+    kind: 'usage-not-configured' | 'package-overridden';
     message: string;
+    /** The asset a `package-overridden` advisory concerns. */
+    assetId?: string;
 }
 export declare function runCheck(projectRoot: string, registry?: ServerPluginRegistry): Promise<CheckReport>;
 /** Pure expansion of a raw classification into canonical hard check findings. */
 export declare function rawCheckFindings(library: Library, raw: RawClassification, registry: ServerPluginRegistry, validationIssues: ValidationIssueDto[]): CheckFinding[];
+/**
+ * The delivered-slot contract: a Package slot that is delivered (explicit member
+ * or in a delivered manifest's reference closure) but has no host-supplied bytes
+ * must be filled. A slot with an `importSource` is `slot-unmaterialized` (run
+ * import); a slot with nothing is `slot-unfilled`. Inert (undelivered) slots
+ * produce no finding.
+ */
+export declare function packageSlotFindings(library: EffectiveLibrary, provenance: MergeProvenance, membership: LibraryMembership): CheckFinding[];

package/dist/server/check.js

@@ -10,13 +10,13 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { collectAllReferences, compareCodeUnits, computeLibraryMembership, rawFileNameOfPath, typesForFileName } from '../core/index.js';
+import { allDeliveredAssetIds, collectAllReferences, compareCodeUnits, computeLibraryMembership, flatLibraryIssues, materializeLibrary, mergePackages, rawFileNameOfPath, typesForFileName } from '../core/index.js';
 import { loadConfig, USAGE_NOT_CONFIGURED_MESSAGE } from './config-loader.js';
 import { LibraryStore } from './library-store.js';
 import { classifyRawDirectory } from './raw-reconciliation.js';
-import { buildManifestEntries, manifestModuleFileName, renderManifestModule, strayGeneratedModuleNames } from './codegen.js';
+import { buildManifestEntries, manifestModuleCollisionIssues, manifestModuleFileName, renderManifestModule, strayGeneratedModuleNames } from './codegen.js';
 import { descriptorsByType, serverPluginsByType } from './plugins.js';
-import { deliveredAssetIds, expectedProxyRelativePath, isProxyFileName, readCurrentProxy } from './processing/processor.js';
+import { expectedProxyRelativePath, isProxyFileName, readCurrentProxy } from './processing/processor.js';
 import { listRelativeFiles } from './folder-filesystem.js';
 import { ImageDuplicateDetector } from './image-duplicates.js';
 /** The human rendering of a finding — `[assetId] message`, as `fundus check` prints it. */
@@ -26,18 +26,47 @@ export function formatCheckFinding(finding) {
 export async function runCheck(projectRoot, registry = serverPluginsByType) {
     const config = await loadConfig(projectRoot);
     const store = new LibraryStore(config, registry);
-    const library = await store.read();
+    const host = await store.read();
+    // Merge Packages under the host into one in-memory effective library. Raw
+    // scans stay on the host (it owns the bytes); everything id-space runs over
+    // the effective library; processing/codegen run over the materialized subset.
+    const { library: effective, provenance, findings: mergeFindings } = mergePackages(host, config.packages ?? []);
+    const materialized = materializeLibrary(effective);
     const report = {
         errors: [],
         warnings: [],
         advisories: config.usage === null
             ? [{ kind: 'usage-not-configured', message: USAGE_NOT_CONFIGURED_MESSAGE }]
             : [],
-        assetCount: Object.keys(library.assets).length,
-        manifestCount: Object.keys(library.manifests).length
+        assetCount: Object.keys(effective.assets).length,
+        manifestCount: Object.keys(effective.manifests).length
     };
-    // 1. Library validation (structure, parameters, raw pointers, references).
-    const issues = await store.validate(library);
+    // Merge findings: collisions/type-mismatches are hard errors; an active
+    // override is an auditable, non-fatal advisory.
+    for (const finding of mergeFindings) {
+        if (finding.kind === 'package-overridden') {
+            report.advisories.push({
+                kind: 'package-overridden',
+                message: finding.message,
+                assetId: finding.assetId
+            });
+        }
+        else {
+            report.errors.push({
+                kind: finding.kind,
+                message: finding.message,
+                assetId: finding.assetId
+            });
+        }
+    }
+    // 1. Library validation. Disk/host checks run on the host library; flat-space
+    // checks (id/type/parameters/membership/appearance/references + module
+    // collisions) run over the effective library.
+    const issues = [
+        ...(await store.validate(host, { flatSpace: false })),
+        ...flatLibraryIssues(effective, descriptorsByType(registry)),
+        ...manifestModuleCollisionIssues(effective.manifests)
+    ];
     const validationKeys = new Set();
     for (const issue of issues) {
         const key = `${issue.assetId ?? ''}|${issue.message}`;
@@ -51,16 +80,24 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
         });
     }
     const descriptors = Object.values(registry).map((plugin) => plugin.descriptor);
-    const raw = await classifyRawDirectory(config.rawDir, library, (path) => typesForFileName(path, descriptors).length > 0);
-    report.errors.push(...rawCheckFindings(library, raw, registry, issues));
+    const raw = await classifyRawDirectory(config.rawDir, host, (path) => typesForFileName(path, descriptors).length > 0);
+    report.errors.push(...rawCheckFindings(host, raw, registry, issues));
+    // Delivered set + membership over the effective library, so delivered slots
+    // are analysed and cross-Package references resolve.
+    const referencesByAsset = collectAllReferences(effective, descriptorsByType(registry));
+    const membership = computeLibraryMembership(effective, referencesByAsset);
+    const delivered = allDeliveredAssetIds(membership);
+    report.errors.push(...packageSlotFindings(effective, provenance, membership));
     // 2. Proxies: every delivered asset's expected proxy exists (staleness is a
-    // name check), and the proxy directory holds no orphans.
-    const delivered = deliveredAssetIds(library, registry);
+    // name check), and the proxy directory holds no orphans. Raw-less delivered
+    // slots are covered by the slot findings above and skipped here.
     const expectedProxyPaths = new Set();
     const proxies = {};
     let proxiesComplete = true;
     for (const assetId of [...delivered].sort(compareCodeUnits)) {
-        const record = library.assets[assetId];
+        const record = materialized.assets[assetId];
+        if (!record)
+            continue;
         let proxy;
         try {
             proxy = await readCurrentProxy(assetId, record, config, registry);
@@ -108,12 +145,12 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
     // regeneration. Only meaningful when validation passed and every proxy
     // exists — otherwise regeneration is impossible and already reported.
     if (report.errors.length === 0 && proxiesComplete) {
-        await checkGeneratedModules(report, library, config, proxies, registry);
-        await checkStrayModules(report, library, config);
+        await checkGeneratedModules(report, materialized, config, proxies, registry);
+        await checkStrayModules(report, materialized, config);
     }
     // 4. Advisory warnings. Raw drift is always a hard CI failure.
-    collectUnreachableAssets(report, library, delivered);
-    collectPotentialImageDuplicates(report, await new ImageDuplicateDetector().find(library, config.rawDir));
+    collectUnreachableAssets(report, effective, provenance, delivered);
+    collectPotentialImageDuplicates(report, await new ImageDuplicateDetector().find(host, config.rawDir));
     report.errors.sort((left, right) => compareCodeUnits(`${left.fileName ?? ''}|${left.assetId ?? ''}|${left.kind}|${left.message}`, `${right.fileName ?? ''}|${right.assetId ?? ''}|${right.kind}|${right.message}`));
     report.warnings.sort((left, right) => compareCodeUnits(`${left.assetId ?? ''}|${left.kind}|${left.message}`, `${right.assetId ?? ''}|${right.kind}|${right.message}`));
     return report;
@@ -254,15 +291,66 @@ async function checkStrayModules(report, library, config) {
  * no explicit membership AND no passive membership in any manifest. An asset
  * that is only passively delivered (referenced by a delivered asset) is fine.
  */
-function collectUnreachableAssets(report, library, delivered) {
+function collectUnreachableAssets(report, library, provenance, delivered) {
+    for (const [assetId, record] of Object.entries(library.assets)) {
+        if (record.manifests.length !== 0 || delivered.has(assetId))
+            continue;
+        // An inert, unfilled Package slot is not a host mistake — a Package ships
+        // a superset of slots and the app delivers a subset. Only host/override
+        // assets (and filled slots) warn.
+        if (record.raw === undefined && provenance[assetId]?.source === 'package')
+            continue;
+        report.warnings.push({
+            kind: 'unreachable-asset',
+            message: 'In no manifest and not referenced by any delivered asset — ' +
+                'nothing is processed or generated for it.',
+            assetId
+        });
+    }
+}
+/**
+ * The delivered-slot contract: a Package slot that is delivered (explicit member
+ * or in a delivered manifest's reference closure) but has no host-supplied bytes
+ * must be filled. A slot with an `importSource` is `slot-unmaterialized` (run
+ * import); a slot with nothing is `slot-unfilled`. Inert (undelivered) slots
+ * produce no finding.
+ */
+export function packageSlotFindings(library, provenance, membership) {
+    const deliveringManifests = new Map();
+    for (const [name, manifestMembership] of Object.entries(membership)) {
+        for (const assetId of manifestMembership.deliveredAssetIds) {
+            const names = deliveringManifests.get(assetId) ?? [];
+            names.push(name);
+            deliveringManifests.set(assetId, names);
+        }
+    }
+    const findings = [];
     for (const [assetId, record] of Object.entries(library.assets)) {
-        if (record.manifests.length === 0 && !delivered.has(assetId)) {
-            report.warnings.push({
-                kind: 'unreachable-asset',
-                message: 'In no manifest and not referenced by any delivered asset — ' +
-                    'nothing is processed or generated for it.',
-                assetId
+        if (record.raw !== undefined)
+            continue;
+        const names = deliveringManifests.get(assetId);
+        if (!names || names.length === 0)
+            continue;
+        const originRecord = provenance[assetId];
+        const origin = originRecord && originRecord.source !== 'host' ? originRecord.origin : 'a package';
+        const deliveredBy = [...names]
+            .sort(compareCodeUnits)
+            .map((name) => `"${name}"`)
+            .join(', ');
+        if (record.importSource !== undefined) {
+            findings.push({
+                kind: 'slot-unmaterialized',
+                assetId,
+                message: `Slot "${assetId}" (from ${origin}) has an import source but no bytes yet — run import to fill it. Delivered by: ${deliveredBy}.`
+            });
+        }
+        else {
+            findings.push({
+                kind: 'slot-unfilled',
+                assetId,
+                message: `Slot "${assetId}" (from ${origin}) has no bytes, import source, or host override. Delivered by: ${deliveredBy}.`
             });
         }
     }
+    return findings;
 }

package/dist/server/codegen.d.ts

@@ -1,4 +1,4 @@
-import { type AssetRecord, type Library, type ManifestEntry, type ManifestEntryData, type ManifestMembership, type ReferencesByAsset } from '../core/index.js';
+import { type AssetRecord, type Library, type ManifestEntry, type ManifestEntryData, type ManifestMembership, type ManifestName, type ManifestRecord, type ReferencesByAsset, type ValidationIssueDto } from '../core/index.js';
 import type { SourceLocation } from '../core/index.js';
 import type { ResolvedFundusConfig } from './config-loader.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
@@ -10,6 +10,8 @@ export declare function locateGeneratedAssetDeclaration(file: string, source: st
 export declare function kebabCaseFromCamel(name: string): string;
 /** Generated module file name for a manifest. */
 export declare function manifestModuleFileName(manifestName: string): string;
+/** Two manifest names that would generate the same kebab-case module file. */
+export declare function manifestModuleCollisionIssues(manifests: Record<ManifestName, ManifestRecord>): ValidationIssueDto[];
 /**
  * Build the entry data codegen emits for one asset — delegated to
  * the owning server plugin's `buildManifestEntry`. Reference fields

package/dist/server/codegen.js

@@ -35,6 +35,24 @@ export function kebabCaseFromCamel(name) {
 export function manifestModuleFileName(manifestName) {
     return `${kebabCaseFromCamel(manifestName)}.generated.ts`;
 }
+/** Two manifest names that would generate the same kebab-case module file. */
+export function manifestModuleCollisionIssues(manifests) {
+    const issues = [];
+    const namesByModuleFile = new Map();
+    for (const name of Object.keys(manifests)) {
+        const fileName = manifestModuleFileName(name);
+        const existingName = namesByModuleFile.get(fileName);
+        if (existingName !== undefined) {
+            issues.push({
+                message: `Manifests "${existingName}" and "${name}" would both generate "${fileName}".`
+            });
+        }
+        else {
+            namesByModuleFile.set(fileName, name);
+        }
+    }
+    return issues;
+}
 /**
  * Build the entry data codegen emits for one asset — delegated to
  * the owning server plugin's `buildManifestEntry`. Reference fields

package/dist/server/config-loader.d.ts

@@ -1,4 +1,4 @@
-import type { AudioPreset, FigmaImportScale, ImagePreset, ResolvedVideoPreset, UsageConfig } from '../core/index.js';
+import { type AudioPreset, type FigmaImportScale, type ImagePreset, type PackageDeclaration, type ResolvedVideoPreset, type UsageConfig } from '../core/index.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 export interface ResolvedPresetPluginConfig {
     presets: Record<string, ImagePreset>;
@@ -13,6 +13,27 @@ export interface ResolvedVideoPluginConfig {
 export interface ResolvedAudioPluginConfig {
     presets: Record<string, AudioPreset>;
 }
+/**
+ * A `packages` entry after pure normalization (no disk): its declared origin,
+ * whether it is a package name or a path, the resolved reference (absolute path
+ * for the path form; the bare name for the name form), and an optional raw-root
+ * override. Package files are read later, in `loadConfig`.
+ */
+export interface NormalizedPackageSource {
+    origin: string;
+    kind: 'name' | 'path';
+    reference: string;
+    rawDirOverride?: string;
+}
+/** A fully resolved Package: its parsed declaration plus provenance. */
+export interface ResolvedPackage {
+    origin: string;
+    /** Absolute path of the resolved fundus.package.json. */
+    file: string;
+    /** Absolute raw root (recorded for provenance; unused in v1 slots-only). */
+    rawDir: string;
+    declaration: PackageDeclaration;
+}
 export interface ResolvedFundusConfig {
     /** Absolute host project directory containing fundus.config.ts. */
     projectRoot: string;
@@ -39,9 +60,22 @@ export interface ResolvedFundusConfig {
         };
     };
     usage: UsageConfig | null;
+    /** Normalized `packages` entries (from the pure `resolveConfig`, no disk). */
+    packageSources: NormalizedPackageSource[];
+    /** Parsed Packages (filled by `loadConfig`; always [] from `resolveConfig`). */
+    packages: ResolvedPackage[];
 }
 export declare const USAGE_NOT_CONFIGURED_MESSAGE = "Usage analysis is not configured; add usage.referenceProvider and usage.openLocation to fundus.config.ts.";
 /** Pure resolution step (testable without a config file on disk). */
 export declare function resolveConfig(projectRoot: string, value: unknown, registry?: ServerPluginRegistry): ResolvedFundusConfig;
+/**
+ * Read and parse every declared Package from disk. Name entries resolve through
+ * the host's module resolver (respecting `exports`), then walk up to the nearest
+ * `package.json` that declares the name and read its `"fundus"` field. Path
+ * entries point directly at a `fundus.package.json`. Throws a clear,
+ * origin-tagged error on any resolution/read/parse failure — Package assembly
+ * failures are symmetric with a missing `fundus.config.ts`.
+ */
+export declare function loadPackages(projectRoot: string, sources: NormalizedPackageSource[]): Promise<ResolvedPackage[]>;
 /** Load `fundus.config.ts` from the host project root. */
 export declare function loadConfig(projectRoot: string): Promise<ResolvedFundusConfig>;

package/dist/server/config-loader.js

@@ -3,9 +3,13 @@
  * the shape, resolves all paths to
  * absolute, and merges the built-in plugin preset defaults under the host's.
  */
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { createJiti } from 'jiti';
+import { parsePackageDeclaration, validatePackageDeclaration } from '../core/index.js';
 import { serverPluginsByType } from './plugins.js';
 import { isRecord } from './plugins/config.js';
 export const USAGE_NOT_CONFIGURED_MESSAGE = 'Usage analysis is not configured; add usage.referenceProvider and usage.openLocation to fundus.config.ts.';
@@ -32,6 +36,88 @@ function configDefinitionsFor(registry) {
     }
     return [...byNamespace.values()];
 }
+/**
+ * A string `packages` entry is a *path* when it looks like one (starts with
+ * `.`/`/`, is absolute, or ends `.json`), or a bare relative path with a
+ * separator; otherwise it is a package *name*. A scoped name (`@scope/pkg`)
+ * contains a `/` but is a name.
+ */
+function classifyPackageSpec(spec) {
+    if (spec.startsWith('.') || spec.startsWith('/') || isAbsolute(spec))
+        return 'path';
+    if (DECLARATION_FILE_RE.test(spec))
+        return 'path';
+    if (spec.startsWith('@'))
+        return 'name';
+    if (spec.includes('/') || spec.includes('\\'))
+        return 'path';
+    return 'name';
+}
+/** A declaration file is JSON or a JS/TS module (the latter loaded via jiti). */
+const DECLARATION_FILE_RE = /\.(json|[mc]?[jt]s)$/;
+/**
+ * Read a package declaration from its resolved file: a JSON `fundus.package.json`
+ * (parsed as text) or a JS/TS module (`fundus.package.ts`) whose default export is
+ * the declaration — loaded through the same jiti path as `fundus.config.ts`, which
+ * keeps the resource `type`s literal for the package's `PackageAssets<…>` derivation.
+ */
+async function loadPackageDeclaration(file, origin) {
+    if (/\.[mc]?[jt]s$/.test(file)) {
+        let module;
+        try {
+            const jiti = createJiti(import.meta.url, { interopDefault: false });
+            module = await jiti.import(file);
+        }
+        catch (cause) {
+            throw new Error(`Cannot load fundus package "${origin}" (${file}): ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const value = isRecord(module) && 'default' in module ? module.default : module;
+        return validatePackageDeclaration(value, origin);
+    }
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (cause) {
+        throw new Error(`Cannot read fundus package "${origin}" (${file}): ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    return parsePackageDeclaration(text, origin);
+}
+function normalizePackageSource(projectRoot, entry) {
+    let spec;
+    let rawDirOverride;
+    if (typeof entry === 'string') {
+        spec = entry;
+    }
+    else if (isRecord(entry) && typeof entry.package === 'string' && entry.package.length > 0) {
+        spec = entry.package;
+        if (entry.rawDir !== undefined) {
+            if (typeof entry.rawDir !== 'string' || entry.rawDir.length === 0) {
+                throw new Error('fundus.config: a "packages" entry "rawDir" must be a non-empty string.');
+            }
+            rawDirOverride = entry.rawDir;
+        }
+    }
+    else {
+        throw new Error('fundus.config: each "packages" entry must be a package name, a path string, or { package: string; rawDir?: string }.');
+    }
+    const kind = classifyPackageSpec(spec);
+    const reference = kind === 'path' ? resolve(projectRoot, spec) : spec;
+    return {
+        origin: spec,
+        kind,
+        reference,
+        ...(rawDirOverride !== undefined ? { rawDirOverride } : {})
+    };
+}
+function resolvePackageSources(projectRoot, value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error('fundus.config: "packages" must be an array.');
+    }
+    return value.map((entry) => normalizePackageSource(projectRoot, entry));
+}
 /** Pure resolution step (testable without a config file on disk). */
 export function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
     if (!isRecord(value)) {
@@ -95,9 +181,103 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
                 defaults: { scale }
             }
         },
-        usage: usage === undefined ? null : usage
+        usage: usage === undefined ? null : usage,
+        packageSources: resolvePackageSources(projectRoot, value.packages),
+        packages: []
     };
 }
+function nearestNamedPackageJson(entryPath, name) {
+    let dir = dirname(entryPath);
+    for (;;) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (isRecord(pkg) && pkg.name === name)
+                    return { dir, pkg };
+            }
+            catch {
+                // Malformed package.json — keep walking up.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`Cannot find the package.json for fundus package "${name}" (resolved to ${entryPath}).`);
+}
+/**
+ * Resolve a name-form Package to its root directory + parsed `package.json`. A
+ * declaration-only Package ships no JS entry module, so resolving the bare name
+ * would throw `MODULE_NOT_FOUND`; resolve its `package.json` subpath first and
+ * only fall back to entry resolution when an `exports` map hides it.
+ */
+function resolvePackageRoot(require, reference, origin) {
+    try {
+        const manifestPath = require.resolve(`${reference}/package.json`);
+        const pkg = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (isRecord(pkg))
+            return { dir: dirname(manifestPath), pkg };
+    }
+    catch {
+        // No resolvable ./package.json subpath — fall back to the entry module.
+    }
+    let entry;
+    try {
+        entry = require.resolve(reference);
+    }
+    catch {
+        throw new Error(`Cannot resolve fundus package "${origin}": no installed package declares it — is it a dependency?`);
+    }
+    return nearestNamedPackageJson(entry, reference);
+}
+/**
+ * Read and parse every declared Package from disk. Name entries resolve through
+ * the host's module resolver (respecting `exports`), then walk up to the nearest
+ * `package.json` that declares the name and read its `"fundus"` field. Path
+ * entries point directly at a `fundus.package.json`. Throws a clear,
+ * origin-tagged error on any resolution/read/parse failure — Package assembly
+ * failures are symmetric with a missing `fundus.config.ts`.
+ */
+export async function loadPackages(projectRoot, sources) {
+    const require = createRequire(pathToFileURL(join(projectRoot, 'fundus.config.ts')).href);
+    const packages = [];
+    for (const source of sources) {
+        let file;
+        let defaultRawDir;
+        if (source.kind === 'path') {
+            file = source.reference;
+            if (!existsSync(file)) {
+                throw new Error(`Fundus package file not found: ${file} (from "${source.origin}").`);
+            }
+            defaultRawDir = dirname(file);
+        }
+        else {
+            const { dir, pkg } = resolvePackageRoot(require, source.reference, source.origin);
+            const fundusField = pkg.fundus;
+            if (!isRecord(fundusField) ||
+                typeof fundusField.package !== 'string' ||
+                fundusField.package.length === 0) {
+                throw new Error(`Fundus package "${source.origin}" is missing a "fundus.package" field in its package.json.`);
+            }
+            file = resolve(dir, fundusField.package);
+            if (!existsSync(file)) {
+                throw new Error(`Fundus package "${source.origin}" declaration not found: ${file}.`);
+            }
+            defaultRawDir =
+                typeof fundusField.rawDir === 'string' && fundusField.rawDir.length > 0
+                    ? resolve(dir, fundusField.rawDir)
+                    : dir;
+        }
+        const declaration = await loadPackageDeclaration(file, source.origin);
+        const rawDir = source.rawDirOverride !== undefined
+            ? resolve(projectRoot, source.rawDirOverride)
+            : defaultRawDir;
+        packages.push({ origin: source.origin, file, rawDir, declaration });
+    }
+    return packages;
+}
 /** Load `fundus.config.ts` from the host project root. */
 export async function loadConfig(projectRoot) {
     const root = resolve(projectRoot);
@@ -113,5 +293,6 @@ export async function loadConfig(projectRoot) {
     catch (cause) {
         throw new Error(`Cannot load fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
-    return resolveConfig(root, isRecord(module) && 'default' in module ? module.default : module);
+    const config = resolveConfig(root, isRecord(module) && 'default' in module ? module.default : module);
+    return { ...config, packages: await loadPackages(root, config.packageSources) };
 }

package/dist/server/library-store.d.ts

@@ -26,6 +26,14 @@ export interface IngestOptions {
 export interface CreateAssetOptions extends IngestOptions {
     manifests?: string[];
     importSource?: ImportSourceRecord;
+    /**
+     * Fill/override a Package slot: store these parameters verbatim as a host
+     * override record instead of expanding plugin defaults. Partial by design
+     * (only the overridden keys) — the merge deep-merges them over the Package
+     * base, and they are schema-validated over the effective library, not here.
+     * When set, `prepareParameters` is ignored.
+     */
+    parametersOverride?: unknown;
 }
 export interface CreateAssetStaging {
     rawPath: string;
@@ -124,6 +132,8 @@ export declare class LibraryStore {
      * type, dangling raw pointer, invalid parameters, unknown manifest names,
      * and reference errors (dangling target, type mismatch, cycles).
      */
-    validate(library: Library): Promise<ValidationIssueDto[]>;
+    validate(library: Library, options?: {
+        flatSpace?: boolean;
+    }): Promise<ValidationIssueDto[]>;
     syncFolders(library: Library): Promise<void>;
 }