@yugoo-design/dsh-design-knowledge-ladybug 0.1.0-beta.3 → 0.1.0

package/README.md

@@ -8,6 +8,16 @@ The provider implements the complete `DesignKnowledgeService`. Delta and proposa
 
 Archive import accepts only an empty project namespace. It validates the neutral format, project, proposal digests, relation endpoints, terminal lifecycle decisions, and journal references before beginning a write. Import remaps source proposal revisions explicitly, rewrites decision proposal revisions to the target provider revisions, returns the complete source-to-target map, and commits the reconstruction in one database transaction.
 
+The durable neutral snapshot lives in the Design Project at
+`design_records/knowledge/archive.json`, tracked by project Git. DSH and Companion
+restore it before exposing the provider and save it after settled knowledge
+publication or decisions. `resetCache(projectId)` clears only this provider's
+derived namespace under its existing serialization and transaction. It supports
+restoring changed or older archive bytes and clearing a cache when the project
+has no archive; it is not an old-state migration or permission to promote an
+external database into a new project authority. Provider paths, locks, native
+handles and embeddings remain local runtime data.
+
 The WASM package owns one worker for the Node.js process. Closing a project releases its database and project lock but intentionally keeps the worker available for reopen. Standalone embeddings may call `shutdownLadybugKnowledgeRuntime()` once, after all providers close, during terminal process teardown; opening after terminal shutdown fails loud. The reloadable DSH plugin drains every project handle on unload but leaves the process-global worker available for a later plugin activation.
 
 Configuration resolves once at open. Writer acquisition, project-lock retry, maximum query result, text byte, and filter cardinality budgets are explicit. Invalid queries fail before any database read. Lock or writer exhaustion fails without opening or mutating project state.
@@ -31,4 +41,28 @@ pnpm run build
 pnpm test
 ```
 
+### Local embedding resources
+
+The default model is fixed to one repository revision. Its configuration,
+tokenizer and quantized ONNX weights must match the recorded sizes and Git/LFS
+hashes before a native inference child starts. Resource transfer has a separate
+bounded preparation lifetime; the existing 180-second inference budget is unchanged.
+
+Offline mode verifies the existing files and reports missing or incomplete
+resources without network access. When download is permitted, interrupted
+transfers remain in resumable staging files. Only a complete checksum-verified
+file replaces the canonical cache entry; an invalid previous entry is retained.
+Failure ends that maintenance pass. A later explicit maintenance request can
+resume preparation; display/status reads do not retry it.
+Companion's normal `serve --embedding-cache /absolute/cache` can select an
+explicit prepared cache, including an isolated cache for installation checks.
+Omitting it retains the existing per-user default location.
+
+On macOS, explicit HTTP(S) proxy environment variables take precedence. Otherwise
+the resource downloader and the model child use the existing manual system HTTPS
+proxy and its bypass list. The parent environment, OS settings and TLS validation
+are unchanged. PAC discovery and proxy authentication are not configured here.
+Custom model/revision configurations retain their existing loader behavior; this
+fixed asset inventory describes only the default model.
+
 DesignJournal remains the only human-decision authority. The `./dsh` host entry registers `ladybug-wasm` as the DSH composition's explicit default, derives each database root from external project runtime state, and exposes only `DesignKnowledgeService` to Core consumers. G/R/A scheduling, Studio, compaction, and future Codex/Claude integration remain outside this storage provider.

package/lib/{dsh-plugin-C0TG9tJI.js → dsh-plugin-BWO-rNYF.js}

@@ -1,11 +1,11 @@
-import { DesignSemanticIndex } from "./semantic-index.js";
+import { t as DesignSemanticIndex } from "./semantic-index-CigpMVTO.js";
 import { createRequire } from "node:module";
 import { createHash, randomInt, randomUUID } from "node:crypto";
 import { copyFile, lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { constants, createReadStream } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
-import { DesignKnowledgeCheckpointConflictError, DesignKnowledgeManager, DesignKnowledgeMutationConflictError, DesignKnowledgeMutationId, DesignKnowledgeProposalDigest, DesignKnowledgeProviderId, DesignKnowledgeRevision, DesignKnowledgeRevisionConflictError, assertDesignKnowledgeDecisionAuthority, designKnowledgeProposalDigest, queryKnowledgeSnapshot } from "@yugoo-design/dsh-design-core";
+import { DesignKnowledgeCheckpointConflictError, DesignKnowledgeManager, DesignKnowledgeMutationConflictError, DesignKnowledgeMutationId, DesignKnowledgeProposalDigest, DesignKnowledgeProviderId, DesignKnowledgeRevision, DesignKnowledgeRevisionConflictError, assertDesignKnowledgeDecisionAuthority, commitDesignProjectRecords, designKnowledgeProposalDigest, queryKnowledgeSnapshot, readDesignKnowledgePublication, restoreDesignKnowledgeRecords, saveDesignKnowledgeRecords } from "@yugoo-design/dsh-design-core";
 import lockfile from "proper-lockfile";
 //#region src/codec.ts
 const LIFECYCLES = /* @__PURE__ */ new Set([
@@ -1024,6 +1024,39 @@ var LadybugDesignKnowledgeProvider = class LadybugDesignKnowledgeProvider {
 			});
 		});
 	}
+	/**
+	* Discard this project's derived cache before restoring its project archive.
+	* Call only before exposing the provider to readers; the project files and
+	* their Git history are never touched. Existing provider serialization and
+	* project ownership cover reset plus the caller's subsequent import.
+	*/
+	async resetCache(projectId) {
+		return this.#serialized(async () => {
+			this.#assertProject(projectId);
+			await this.#fixed("CREATE NODE TABLE IF NOT EXISTS DesignSemanticCacheV1(key STRING, payload STRING, PRIMARY KEY(key));");
+			await rm(this.#visibleSidecarPath(), { force: true });
+			await this.#beginWrite();
+			try {
+				await this.#rows("MATCH ()-[v:KnowledgeRelationVersion]->() DELETE v;", {});
+				for (const table of [
+					"KnowledgeEntityVersion",
+					"KnowledgeEntityIdentity",
+					"KnowledgeMutation",
+					"KnowledgeProposal",
+					"KnowledgeDecision",
+					"DesignSemanticCacheV1"
+				]) await this.#fixed(`MATCH (n:${table}) DELETE n;`);
+				await this.#rows("MATCH (m:KnowledgeMeta {project: $project}) SET m.revision = $revision;", {
+					project: this.#projectId,
+					revision: this.#baseline
+				});
+				await this.#commit();
+			} catch (error) {
+				await this.#rollback().catch(() => {});
+				throw error;
+			}
+		});
+	}
 	async importProject(archive) {
 		return this.#serialized(async () => {
 			this.#assertProject(archive.projectId);
@@ -1038,8 +1071,8 @@ var LadybugDesignKnowledgeProvider = class LadybugDesignKnowledgeProvider {
 					this.#rows("MATCH ()-[v:KnowledgeRelationVersion]->() RETURN count(v) AS count;", {}),
 					this.#rows("MATCH (m:KnowledgeMutation) RETURN count(m) AS count;", {})
 				]);
-				if (current !== 0 || occupied.some((rows) => asNumber(rows[0]?.count, "namespace record count") !== 0)) throw new Error("Ladybug Design Knowledge import requires an empty project namespace");
-				let target = 0;
+				if (current !== this.#baseline || occupied.some((rows) => asNumber(rows[0]?.count, "namespace record count") !== 0)) throw new Error("Ladybug Design Knowledge import requires an empty project namespace");
+				let target = current;
 				const mapping = {};
 				const proposalItems = [...validated.proposals].sort((left, right) => parseRevision(left.proposalRevision) - parseRevision(right.proposalRevision));
 				const proposalEntityIds = new Set(proposalItems.flatMap((value) => value.proposal.entities.map((entity) => entity.id)));
@@ -1630,6 +1663,18 @@ function apply(ctx, config = {}) {
 				recoveryStates.set(location.projectId, state);
 			}
 		});
+		try {
+			await restoreDesignKnowledgeRecords({
+				projectRoot: await design.knowledgeProjectRoot(location.projectId),
+				projectId: location.projectId,
+				service: provider,
+				cache: provider,
+				resetCache: () => provider.resetCache(location.projectId)
+			});
+		} catch (error) {
+			await provider.close();
+			throw error;
+		}
 		providers.set(location.projectId, provider);
 		return Object.freeze({
 			projectId: location.projectId,
@@ -1644,6 +1689,23 @@ function apply(ctx, config = {}) {
 		});
 	} });
 	const unregister = design.registerDesignKnowledgeRuntime({
+		persistProjectRecords: async (projectId) => {
+			const provider = providers.get(projectId);
+			if (!provider) throw new Error("Knowledge project cache is not open");
+			const projectRoot = await design.knowledgeProjectRoot(projectId);
+			await saveDesignKnowledgeRecords({
+				projectRoot,
+				projectId,
+				service: provider,
+				cache: provider,
+				publication: await readDesignKnowledgePublication(provider),
+				persist: (paths) => commitDesignProjectRecords({
+					projectRoot,
+					paths,
+					message: "design(knowledge): save project records"
+				})
+			});
+		},
 		recoveryStatus: (projectId) => recoveryStates.get(projectId),
 		retryRecovery: (projectId) => {
 			retries.add(projectId);
@@ -1652,6 +1714,7 @@ function apply(ctx, config = {}) {
 		administration: manager,
 		service: manager.service,
 		semantic: {
+			enabled: semantic.config.provider !== "disabled",
 			identity: semantic.publicationIdentity,
 			publicationCache: (projectId) => providers.get(projectId),
 			read: async (projectId, graph) => {

package/lib/dsh-plugin.js

@@ -1,3 +1,2 @@
-import { i as name, n as apply, r as inject, t as LADYBUG_WASM_PROVIDER_ID } from "./dsh-plugin-C0TG9tJI.js";
-import "./semantic-index.js";
+import { i as name, n as apply, r as inject, t as LADYBUG_WASM_PROVIDER_ID } from "./dsh-plugin-BWO-rNYF.js";
 export { LADYBUG_WASM_PROVIDER_ID, apply, inject, name };

package/lib/embedding-diagnostic-CvIl3TWJ.js

@@ -0,0 +1,104 @@
+//#region src/embedding-diagnostic.ts
+/** Private child IPC vocabulary. Never serialize an exception or its free text. */
+const names = /* @__PURE__ */ new Set([
+	"Error",
+	"TypeError",
+	"SyntaxError",
+	"RangeError",
+	"ReferenceError",
+	"URIError",
+	"EvalError",
+	"AggregateError"
+]);
+const codes = /* @__PURE__ */ new Set([
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"ETIMEDOUT",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_HEADERS_TIMEOUT",
+	"UND_ERR_BODY_TIMEOUT",
+	"CERT_HAS_EXPIRED",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"ERR_TLS_CERT_ALTNAME_INVALID",
+	"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+	"ERR_MODULE_NOT_FOUND",
+	"MODULE_NOT_FOUND",
+	"ERR_DLOPEN_FAILED",
+	"EACCES",
+	"EPERM",
+	"ENOENT",
+	"ENOSPC"
+]);
+const hubPrefixes = [
+	[400, "Bad request error occurred while trying to load file"],
+	[401, "Unauthorized access to file"],
+	[403, "Forbidden access to file"],
+	[404, "Could not locate file"],
+	[408, "Request timeout error occurred while trying to load file"],
+	[500, "Internal server error error occurred while trying to load file"],
+	[502, "Bad gateway error occurred while trying to load file"],
+	[503, "Service unavailable error occurred while trying to load file"],
+	[504, "Gateway timeout error occurred while trying to load file"]
+];
+const hubTokens = new Set(hubPrefixes.map(([status]) => `hf3.8.1-http-${status}`));
+/** Revalidate at the receiving boundary; unknown keys and values never escape. */
+function readEmbeddingDiagnostic(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const result = {}, input = value;
+	try {
+		for (const [key, allowed] of [
+			["name", names],
+			["code", codes],
+			["causeCode", codes],
+			["hubText", hubTokens]
+		]) {
+			if (!Object.hasOwn(input, key)) continue;
+			const item = input[key];
+			if (typeof item === "string" && allowed.has(item)) result[key] = item;
+		}
+		for (const key of ["localOnly", "remoteAllowed"]) {
+			if (!Object.hasOwn(input, key)) continue;
+			const item = input[key];
+			if (typeof item === "boolean") result[key] = item;
+		}
+	} catch {}
+	return Object.keys(result).length ? result : void 0;
+}
+function captureEmbeddingDiagnostic(error, phase, effective) {
+	const result = {}, policy = readEmbeddingDiagnostic(effective);
+	if (policy?.localOnly !== void 0) result.localOnly = policy.localOnly;
+	if (policy?.remoteAllowed !== void 0) result.remoteAllowed = policy.remoteAllowed;
+	try {
+		const seen = /* @__PURE__ */ new Set();
+		let current = error;
+		for (let depth = 0; depth < 3 && current && typeof current === "object" && !seen.has(current); depth++) {
+			seen.add(current);
+			const item = current;
+			const name = item.name;
+			if (!depth && typeof name === "string" && names.has(name)) result.name = name;
+			const code = item.code;
+			if (typeof code === "string" && codes.has(code)) {
+				if (!depth) result.code = code;
+				else result.causeCode ??= code;
+			}
+			const message = item.message;
+			if (!depth && phase === "model" && typeof message === "string" && message.endsWith("\".")) {
+				const matched = hubPrefixes.find(([, prefix]) => message.startsWith(`${prefix}: "`));
+				if (matched) result.hubText = `hf3.8.1-http-${matched[0]}`;
+			}
+			current = item.cause;
+		}
+	} catch {}
+	return readEmbeddingDiagnostic(result);
+}
+/** Closed values keep the suffix below 256 characters, including every field. */
+function embeddingDiagnosticSuffix(value) {
+	const diagnostic = readEmbeddingDiagnostic(value);
+	return diagnostic ? ` [embedding: ${Object.entries(diagnostic).map(([key, item]) => `${key}=${item}`).join("; ")}]` : "";
+}
+//#endregion
+export { embeddingDiagnosticSuffix as n, readEmbeddingDiagnostic as r, captureEmbeddingDiagnostic as t };

package/lib/embedding-worker.js

@@ -1,3 +1,4 @@
+import { t as captureEmbeddingDiagnostic } from "./embedding-diagnostic-CvIl3TWJ.js";
 //#region src/embedding-text.mjs
 /** Exact tokenizer windows. Preserve every character; never silently truncate evidence. */
 function embeddingWindows(text, prefix, tokenizer, limit = 512, maxParts = 32) {
@@ -33,6 +34,7 @@ let extractor;
 process.on("disconnect", () => process.exit(0));
 process.on("message", async ({ texts, config }) => {
 	let phase = "runtime";
+	let effective;
 	try {
 		const { pipeline, env } = await import("@huggingface/transformers");
 		if (process.env.HTTPS_PROXY || process.env.HTTP_PROXY || process.env.https_proxy || process.env.http_proxy) {
@@ -43,6 +45,10 @@ process.on("message", async ({ texts, config }) => {
 		phase = "model";
 		env.cacheDir = config.cacheDir;
 		env.allowRemoteModels = !config.localOnly;
+		effective = {
+			localOnly: config.localOnly,
+			remoteAllowed: env.allowRemoteModels
+		};
 		extractor ??= await pipeline("feature-extraction", config.model, {
 			revision: config.revision,
 			dtype: "q8",
@@ -72,8 +78,12 @@ process.on("message", async ({ texts, config }) => {
 			offset += group.length;
 			return result;
 		}) });
-	} catch {
-		process.send?.({ error: phase });
+	} catch (error) {
+		const diagnostic = captureEmbeddingDiagnostic(error, phase, effective);
+		process.send?.({
+			error: phase,
+			...diagnostic ? { diagnostic } : {}
+		});
 	}
 });
 //#endregion

package/lib/index.d.ts

@@ -57,6 +57,13 @@ declare class LadybugDesignKnowledgeProvider implements LadybugDesignKnowledgeSe
   proposeBatch(batch: DesignKnowledgeProposalBatch): Promise<DesignKnowledgeProposalBatchResult>;
   applyDecision(decision: DesignKnowledgeDecision, pin: Parameters<DesignKnowledgeService['applyDecision']>[1]): Promise<DesignKnowledgeMutationResult>;
   exportProject(projectId: DesignProjectId, requested?: DesignKnowledgeRevision): Promise<DesignKnowledgeArchive>;
+  /**
+   * Discard this project's derived cache before restoring its project archive.
+   * Call only before exposing the provider to readers; the project files and
+   * their Git history are never touched. Existing provider serialization and
+   * project ownership cover reset plus the caller's subsequent import.
+   */
+  resetCache(projectId: DesignProjectId): Promise<void>;
   importProject(archive: DesignKnowledgeArchive): Promise<DesignKnowledgeImportReport>;
 }
 //#endregion

package/lib/index.js

@@ -1,3 +1,3 @@
-import { a as LADYBUG_KNOWLEDGE_SCHEMA_VERSION, c as LadybugSchemaMismatchError, d as shutdownLadybugKnowledgeRuntime, f as resolveLadybugKnowledgeConfig, i as name, l as LadybugWriterBusyError, n as apply, o as LadybugDesignKnowledgeProvider, r as inject, s as LadybugProjectLockError, t as LADYBUG_WASM_PROVIDER_ID, u as isRecoverableLadybugError } from "./dsh-plugin-C0TG9tJI.js";
-import { DesignSemanticIndex } from "./semantic-index.js";
+import { a as LADYBUG_KNOWLEDGE_SCHEMA_VERSION, c as LadybugSchemaMismatchError, d as shutdownLadybugKnowledgeRuntime, f as resolveLadybugKnowledgeConfig, i as name, l as LadybugWriterBusyError, n as apply, o as LadybugDesignKnowledgeProvider, r as inject, s as LadybugProjectLockError, t as LADYBUG_WASM_PROVIDER_ID, u as isRecoverableLadybugError } from "./dsh-plugin-BWO-rNYF.js";
+import { t as DesignSemanticIndex } from "./semantic-index-CigpMVTO.js";
 export { DesignSemanticIndex, LADYBUG_KNOWLEDGE_SCHEMA_VERSION, LADYBUG_WASM_PROVIDER_ID, LadybugDesignKnowledgeProvider, LadybugProjectLockError, LadybugSchemaMismatchError, LadybugWriterBusyError, apply as applyDshLadybugKnowledge, inject as dshLadybugKnowledgeInject, name as dshLadybugKnowledgeName, isRecoverableLadybugError, resolveLadybugKnowledgeConfig, shutdownLadybugKnowledgeRuntime };