@avantf/dsh-mem 0.1.0

package/lib/types/envinit-bootstrap.js

@@ -0,0 +1,323 @@
+/**
+ * Resolve the framework copy the caller's tree already has.
+ * @module bootstrap
+ */
+import { promises as fsp } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+/** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
+export const VERSION = '0.1.3';
+/** The framework interval this bootstrap can launch. */
+export const supportedRange = '^0.1.3';
+const PACKAGE = '@avantf/dsh-envinit';
+function parseVersion(input) {
+    const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(input.trim());
+    if (match === null)
+        return undefined;
+    const minor = match[2] === undefined ? undefined : Number(match[2]);
+    const patch = match[3] === undefined ? undefined : Number(match[3]);
+    const parts = patch !== undefined ? 3 : minor !== undefined ? 2 : 1;
+    const pre = match[4] === undefined || match[4] === '' ? [] : match[4].split('.').map(part => (/^\d+$/.test(part) ? Number(part) : part));
+    return { major: Number(match[1]), minor: minor ?? 0, patch: patch ?? 0, pre, parts };
+}
+function comparePre(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+        const left = a[index];
+        const right = b[index];
+        if (left === undefined)
+            return -1;
+        if (right === undefined)
+            return 1;
+        if (typeof left === 'number' && typeof right === 'number') {
+            if (left !== right)
+                return left - right;
+        }
+        else if (typeof left === 'number')
+            return -1;
+        else if (typeof right === 'number')
+            return 1;
+        else if (left !== right)
+            return left < right ? -1 : 1;
+    }
+    return 0;
+}
+function compare(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    if (a.patch !== b.patch)
+        return a.patch - b.patch;
+    return comparePre(a.pre, b.pre);
+}
+function tuple(major, minor, patch) {
+    return { major, minor, patch, pre: [], parts: 3 };
+}
+/** The next release boundary a partial `>`/`<=` desugars to. */
+function bumpPartial(partial, keepPrerelease) {
+    const pre = keepPrerelease ? partial.pre : [];
+    if (partial.parts === 2)
+        return { major: partial.major, minor: partial.minor + 1, patch: 0, pre, parts: 3 };
+    return { major: partial.major + 1, minor: 0, patch: 0, pre, parts: 3 };
+}
+/** Expand one range token into comparators; `undefined` for a token outside the subset. */
+function comparatorsOf(token) {
+    const match = /^(\^|~|>=|<=|>|<|=)?(.*)$/.exec(token);
+    if (match === null)
+        return undefined;
+    const operator = match[1] ?? '';
+    const partial = parseVersion(match[2] ?? '');
+    if (partial === undefined)
+        return undefined;
+    switch (operator) {
+        case '>':
+            // A partial `>1.2` desugars to `>=1.3.0`.
+            return partial.parts === 3 ? [{ op: '>', version: partial }] : [{ op: '>=', version: bumpPartial(partial, true) }];
+        case '<=':
+            // A partial `<=1.2` desugars to `<1.3.0`.
+            return partial.parts === 3 ? [{ op: '<=', version: partial }] : [{ op: '<', version: bumpPartial(partial, false) }];
+        case '>=':
+        case '<':
+            return [{ op: operator, version: partial }];
+        case '':
+        case '=':
+            if (partial.parts === 3)
+                return [{ op: '=', version: partial }];
+            if (partial.parts === 2)
+                return [{ op: '>=', version: partial }, { op: '<', version: tuple(partial.major, partial.minor + 1, 0) }];
+            return [{ op: '>=', version: partial }, { op: '<', version: tuple(partial.major + 1, 0, 0) }];
+        case '^': {
+            const upper = partial.major > 0 || partial.parts === 1
+                ? tuple(partial.major + 1, 0, 0)
+                : partial.minor > 0 || partial.parts === 2
+                    ? tuple(0, partial.minor + 1, 0)
+                    : tuple(0, 0, partial.patch + 1);
+            return [{ op: '>=', version: partial }, { op: '<', version: upper }];
+        }
+        case '~': {
+            const upper = partial.parts === 1 ? tuple(partial.major + 1, 0, 0) : tuple(partial.major, partial.minor + 1, 0);
+            return [{ op: '>=', version: partial }, { op: '<', version: upper }];
+        }
+        default:
+            return undefined;
+    }
+}
+function matchesComparator(version, comparator) {
+    const order = compare(version, comparator.version);
+    switch (comparator.op) {
+        case '=':
+            return order === 0;
+        case '>':
+            return order > 0;
+        case '>=':
+            return order >= 0;
+        case '<':
+            return order < 0;
+        case '<=':
+            return order <= 0;
+    }
+}
+/**
+ * Does `parsed` satisfy `range`? Unsupported tokens answer `false`.
+ * A prerelease only matches a comparator naming a prerelease of the same tuple.
+ */
+function satisfies(parsed, range) {
+    const text = range.trim();
+    if (text === '')
+        return false;
+    if (text === '*')
+        return true;
+    return text.split('||').some(branch => {
+        const tokens = branch.trim().split(/[\s,]+/).filter(token => token !== '');
+        if (tokens.length === 0)
+            return false;
+        const comparators = [];
+        for (const token of tokens) {
+            const expanded = comparatorsOf(token);
+            if (expanded === undefined)
+                return false;
+            comparators.push(...expanded);
+        }
+        if (!comparators.every(comparator => matchesComparator(parsed, comparator)))
+            return false;
+        if (parsed.pre.length === 0)
+            return true;
+        return comparators.some(comparator => comparator.version.pre.length > 0 &&
+            comparator.version.major === parsed.major &&
+            comparator.version.minor === parsed.minor &&
+            comparator.version.patch === parsed.patch);
+    });
+}
+/** Does `version` fall inside the `supported` interval? */
+function withinSupported(version, supported) {
+    const parsed = parseVersion(version);
+    return parsed !== undefined && satisfies(parsed, supported);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+/** Read `<dir>/package.json` as an object, or `undefined`. */
+async function readManifest(dir) {
+    try {
+        const parsed = JSON.parse(await fsp.readFile(join(dir, 'package.json'), 'utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The entry file a `package.json` points at (`.` export → `main` → `index.js`). */
+function entryOf(dir, manifest) {
+    const exported = manifest['exports'];
+    let relative;
+    if (typeof exported === 'string')
+        relative = exported;
+    else if (typeof exported === 'object' && exported !== null) {
+        const dot = exported['.'] ?? exported;
+        if (typeof dot === 'string')
+            relative = dot;
+        else if (typeof dot === 'object' && dot !== null) {
+            const conditions = dot;
+            for (const key of ['import', 'default', 'require']) {
+                const value = conditions[key];
+                if (typeof value === 'string') {
+                    relative = value;
+                    break;
+                }
+            }
+        }
+    }
+    if (relative === undefined && typeof manifest['main'] === 'string')
+        relative = manifest['main'];
+    return join(dir, relative ?? 'index.js');
+}
+/**
+ * Report the framework copy this caller's tree resolves to, or `undefined` with a warning.
+ * Never throws and never installs anything.
+ *
+ * @param options - the logger and an optional interval override.
+ * @returns the located copy, or `undefined` when it is absent or outside the interval.
+ */
+export async function ensureFramework(options) {
+    const warn = (message) => {
+        try {
+            options.logger?.warn(`bootstrap: ${message}`);
+        }
+        catch {
+            // The warning is best-effort.
+        }
+    };
+    try {
+        if (options.supportedRange !== undefined && typeof options.supportedRange !== 'string') {
+            warn(`supportedRange must be a string; got ${typeof options.supportedRange}`);
+            return undefined;
+        }
+        const supported = options.supportedRange ?? supportedRange;
+        let dir;
+        try {
+            dir = dirname(createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`));
+        }
+        catch {
+            warn(`${PACKAGE} is not installed for this plugin — install it with the package manager (pnpm install)`);
+            return undefined;
+        }
+        const manifest = await readManifest(dir);
+        const version = typeof manifest?.['version'] === 'string' ? manifest['version'] : undefined;
+        if (manifest === undefined || version === undefined) {
+            warn(`${join(dir, 'package.json')} is missing or has no version`);
+            return undefined;
+        }
+        if (!withinSupported(version, supported)) {
+            warn(`the installed ${PACKAGE}@${version} is outside supportedRange "${supported}"; install a supported version`);
+            return undefined;
+        }
+        return { url: pathToFileURL(entryOf(dir, manifest)).href, version, dir, source: 'resolved' };
+    }
+    catch (error) {
+        warn(`unexpected failure: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/** `ensureFramework` + a dynamic `import()` of the located module; never throws. */
+export async function loadFramework(options) {
+    try {
+        const location = await ensureFramework(options);
+        if (location === undefined)
+            return undefined;
+        return (await import(location.url));
+    }
+    catch (error) {
+        try {
+            options.logger?.warn(`bootstrap: could not load ${PACKAGE}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        catch {
+            // best-effort
+        }
+        return undefined;
+    }
+}
+/**
+ * Read the range a plugin declares in the nearest `package.json`: walk up from `from`,
+ * preferring `peerDependencies` over `devDependencies`; `undefined` when none is found.
+ */
+export async function readDependencyRange(from = process.cwd()) {
+    let current = from;
+    if (from.startsWith('file:')) {
+        try {
+            current = fileURLToPath(from);
+        }
+        catch {
+            // A malformed `file:` URL yields no range.
+            return undefined;
+        }
+    }
+    try {
+        const info = await fsp.stat(current);
+        if (info.isFile())
+            current = dirname(current);
+    }
+    catch {
+        // Not an existing path: treat it as a starting directory and walk up from its parent.
+        const parent = dirname(current);
+        if (parent !== current)
+            current = parent;
+    }
+    for (;;) {
+        const manifestPath = join(current, 'package.json');
+        let text;
+        try {
+            text = await fsp.readFile(manifestPath, 'utf8');
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return undefined;
+            current = parent;
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== 'object' || parsed === null)
+                return undefined;
+            const manifest = parsed;
+            return rangeOf(manifest['peerDependencies']) ?? rangeOf(manifest['devDependencies']);
+        }
+        catch {
+            // The nearest manifest is unparseable: stop.
+            return undefined;
+        }
+    }
+}
+function rangeOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const range = value[PACKAGE];
+    return typeof range === 'string' && range.trim() !== '' ? range : undefined;
+}

package/lib/types/envinit.d.ts

@@ -0,0 +1,145 @@
+import type { ProvisionReportEntry } from '@avantf/dsh-envinit';
+import { type CompatModule, type CompatRuntime } from './provision.js';
+/** The framework's module shape; `import type` only — the value is always loaded dynamically. */
+type EnvinitModule = typeof import('@avantf/dsh-envinit');
+/**
+ * The item ids. `resolve()` / `onSettled` are keyed by them, so the DSH plugin compares against these
+ * names rather than re-spelling literals.
+ */
+export declare const COMPAT_ITEM = "mem:compat";
+export declare const PANDOC_ITEM = "mem:pandoc";
+export declare const MODEL_ITEM = "mem:model";
+/**
+ * The default ONNX embedding repository — the one `semantic.local_model` defaults to and the one
+ * {@link MODEL_FILES} describes. A DIFFERENT repo is a different file set, which is why the item
+ * omits `spec.files` for it (see {@link managedModelSpec}).
+ */
+export declare const DEFAULT_MODEL_REPO = "Xenova/bge-small-zh-v1.5";
+/**
+ * The files the local embedding runtime actually requests for the DEFAULT ONNX model.
+ *
+ * Measured, not guessed: with an empty cache, `@huggingface/transformers@4.x` resolving
+ * `feature-extraction` for `Xenova/bge-small-zh-v1.5` fetches exactly these four — `config.json`,
+ * `tokenizer.json`, `tokenizer_config.json` and the fp32 `onnx/model.onnx`. The repo ALSO carries
+ * `special_tokens_map.json`, `vocab.txt` and seven other ONNX quantisations the default run never
+ * opens; declaring them would download hundreds of megabytes of dead weight. The list stays narrow
+ * to what is read.
+ */
+export declare const MODEL_FILES: readonly string[];
+/** The logging surface this module needs — `AvantfLogger` satisfies it. */
+export interface EnvinitLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/**
+ * What the engine resolved from its config, handed to {@link EnvinitRuntime.provisionResources}.
+ *
+ * `pandoc` is "this build needs it": when `tools.auto_install` is off the item is NOT declared, so the
+ * framework never fetches something the operator disabled per feature. The model is declared either
+ * way (unless the runtime reads its models elsewhere), because WHEN it is off is a DOWNLOAD question,
+ * not a declaration question — see {@link ResourcePlan.modelAutoDownload}.
+ */
+export interface ResourcePlan {
+    readonly pandoc: boolean;
+    /** `tools.mirror` — URL templates tried before the official source, for archive downloads. */
+    readonly archiveMirrors: readonly string[];
+    /**
+     * May the MODEL item fetch from the network? `semantic.auto_download`.
+     *
+     * Passed per call, because only the runtime knows the resolved config: the framework's own
+     * `autoDownload` policy was fixed before the config existed, so `semantic.auto_download: false`
+     * used to be ignored and the item still went to the network. Off → the item is still declared (its
+     * terminal state is `skipped (policy/download-disabled)`, the diagnosis an operator looks for) but
+     * the framework probes disk only; the engine then degrades to FTS+entity.
+     */
+    readonly modelAutoDownload: boolean;
+    /**
+     * The embedding model to provision through `model-cache`, or `undefined` when the semantic backend
+     * is not a local model OR the runtime reads its models from somewhere the framework does not own
+     * (an `AVANTF_MEM_MODEL_CACHE` override — see {@link managedModelSpec}). `endpoint` is the
+     * resolved mirror, `files` the explicit set the runtime reads for the DEFAULT repo (empty for any
+     * other repo, where the item falls back to the repository's own file list).
+     */
+    readonly model: {
+        readonly repo: string;
+        readonly files: readonly string[];
+        readonly endpoint: string;
+    } | undefined;
+}
+/**
+ * The model item the framework should own, or `undefined` when it should not.
+ *
+ * Two refusals, both deliberate:
+ *
+ *   1. **Not a local backend** — nothing to provision.
+ *   2. **The runtime reads its models from elsewhere** — `semantic.cache_dir` is not the framework's
+ *      `<home>/models`. That happens through the operator escape hatch `AVANTF_MEM_MODEL_CACHE`
+ *      (env layer ④): the runtime loads from that directory, so a `mem:model` item would install a
+ *      full second copy under `<home>/models` that nothing ever reads (~190 MB). Declaring nothing
+ *      is the fix; the caller warms from the override directory instead.
+ *
+ * `files` is the narrow {@link MODEL_FILES} set only for the DEFAULT repo; a user-changed repo has a
+ * different file set, and a stale six-file list would make the item `failed` while the runtime could
+ * serve it. Empty means "omit `spec.files`": the framework then installs the repository's own file
+ * list.
+ */
+export declare function managedModelSpec(semantic: {
+    readonly backend: string;
+    readonly local_model: string;
+    readonly cache_dir: string;
+    readonly mirror: string;
+}, modelsRoot: string): ResourcePlan['model'];
+/** The loaded framework + gate + the roots the runtime should use. */
+export interface EnvinitRuntime {
+    /** The family root (`<home>` of the framework); resources live under it. */
+    readonly home: string;
+    /** The gate runtime, or `undefined` when the base could not be provided (mount anyway). */
+    readonly compat: CompatRuntime | undefined;
+    /** The engine's managed roots while the framework is usable. */
+    readonly roots: {
+        readonly tools: string;
+        readonly models: string;
+    };
+    /**
+     * Declare the expensive resources and dispatch them in the BACKGROUND.
+     *
+     * Returns immediately; each item reaches `onSettled` when it settles (usually `present` right
+     * away, or `installed`/`failed`/`skipped` later). A callback that throws is logged by the
+     * framework, never fatal.
+     */
+    provisionResources(plan: ResourcePlan, onSettled: (entry: ProvisionReportEntry) => void): void;
+    /** Release every provisioner this runtime created (leases included). */
+    dispose(): void;
+}
+/** Options for {@link loadEnvinit}. */
+export interface EnvinitLoadOptions {
+    readonly log?: EnvinitLogger;
+    /** The family root; default `$AVANTF_HOME`, else `~/.avantf/env` (framework DESIGN §6.3). */
+    readonly home?: string;
+    /** May a missing resource be downloaded? Default both kill switches on (see `envAutoDownload` in the contract). */
+    readonly autoDownload?: boolean;
+    readonly deadlineMs?: number;
+    /** Test seam: the framework module, instead of bootstrapping it from the tree/registry. */
+    readonly framework?: EnvinitModule;
+    /** Test seam: the base module, instead of importing the copy the framework provisioned. */
+    readonly compatModule?: CompatModule;
+}
+/**
+ * Ensure the framework, then the compatibility base, then dispatch the expensive resources.
+ *
+ * Never throws. Returns `undefined` when the framework cannot be loaded — the caller then warns and
+ * mounts on the legacy provisioning path (the engine's own `@avantf/mem-provision` sweep, whose
+ * default directories are the pre-migration ones). A framework that loads but cannot provide the
+ * base still returns a runtime, with `compat: undefined`: the mount must continue, and the resource
+ * items are still worth dispatching.
+ *
+ * The result is cached per process; a FAILED load is not, so a profile reload retries instead of
+ * replaying the first failure for the whole process lifetime.
+ *
+ * @param options - logger, family root, download policy and the test seams.
+ * @returns the loaded runtime, or `undefined` when the framework itself is unavailable.
+ */
+export declare function loadEnvinit(options?: EnvinitLoadOptions): Promise<EnvinitRuntime | undefined>;
+export {};
+//# sourceMappingURL=envinit.d.ts.map

package/lib/types/envinit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envinit.d.ts","sourceRoot":"","sources":["../../src/envinit.ts"],"names":[],"mappings":"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"}