@alan512/experienceengine 0.3.6 → 0.4.0

package/dist/store/vector/offline-manifest.js

@@ -0,0 +1,162 @@
+import { readFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, dirname, isAbsolute } from "node:path";
+import { createHash } from "node:crypto";
+export const isSafeRelativePath = (p) => {
+    if (typeof p !== "string" || !p)
+        return false;
+    if (isAbsolute(p))
+        return false;
+    if (/^[a-zA-Z]:/.test(p))
+        return false;
+    const parts = p.split(/[/\\]/);
+    for (const part of parts) {
+        if (part === ".." || part === ".") {
+            return false;
+        }
+    }
+    return true;
+};
+export const calculateFileSha256 = (filePath) => {
+    const content = readFileSync(filePath);
+    return createHash("sha256").update(content).digest("hex");
+};
+export const validateOfflineManifest = (manifest, baseDir) => {
+    if (!manifest || typeof manifest !== "object") {
+        throw new Error("Invalid manifest format: not an object.");
+    }
+    const m = manifest;
+    if (typeof m.manifestVersion !== "string" || !m.manifestVersion) {
+        throw new Error("Missing or invalid manifestVersion.");
+    }
+    if (m.providerId !== "local") {
+        throw new Error(`Unsupported providerId: ${m.providerId}. Only 'local' is supported.`);
+    }
+    if (typeof m.modelId !== "string" || !m.modelId) {
+        throw new Error("Missing or invalid modelId.");
+    }
+    if (typeof m.dimensions !== "number" || m.dimensions <= 0) {
+        throw new Error("Missing or invalid dimensions.");
+    }
+    if (typeof m.preprocessingVersion !== "string" || !m.preprocessingVersion) {
+        throw new Error("Missing or invalid preprocessingVersion.");
+    }
+    if (!m.assets || typeof m.assets !== "object") {
+        throw new Error("Missing or invalid assets object.");
+    }
+    const validatedAssets = {};
+    const assetsObj = m.assets;
+    for (const [key, value] of Object.entries(assetsObj)) {
+        if (!value || typeof value !== "object") {
+            throw new Error(`Invalid asset entry for key: ${key}.`);
+        }
+        const val = value;
+        if (typeof val.path !== "string" || !val.path || !isSafeRelativePath(val.path)) {
+            throw new Error(`Missing, invalid, or unsafe path for asset: ${key}. Path traversal detected or suspected.`);
+        }
+        if (typeof val.sha256 !== "string" || !val.sha256) {
+            throw new Error(`Missing or invalid sha256 checksum for asset: ${key}.`);
+        }
+        // Validate file presence and sha256
+        const absolutePath = join(baseDir, val.path);
+        if (!existsSync(absolutePath)) {
+            throw new Error(`Asset file missing: ${absolutePath}`);
+        }
+        const actualSha256 = calculateFileSha256(absolutePath);
+        if (actualSha256 !== val.sha256) {
+            throw new Error(`Asset checksum mismatch for file ${val.path}. Expected: ${val.sha256}, Actual: ${actualSha256}`);
+        }
+        validatedAssets[key] = {
+            path: val.path,
+            sha256: val.sha256
+        };
+    }
+    let manifestId = typeof m.id === "string" ? m.id : undefined;
+    if (!manifestId) {
+        const assetKeysSorted = Object.keys(validatedAssets).sort();
+        const assetsString = assetKeysSorted
+            .map((key) => `${key}:${validatedAssets[key].sha256}`)
+            .join(";");
+        const idSource = `${m.modelId}|${m.dimensions}|${m.preprocessingVersion}|${assetsString}`;
+        manifestId = `derived-${createHash("sha256").update(idSource).digest("hex").slice(0, 16)}`;
+    }
+    return {
+        id: manifestId,
+        manifestVersion: m.manifestVersion,
+        providerId: m.providerId,
+        modelId: m.modelId,
+        dimensions: m.dimensions,
+        preprocessingVersion: m.preprocessingVersion,
+        assets: validatedAssets,
+        license: typeof m.license === "string" ? m.license : undefined,
+        sourceMetadata: typeof m.sourceMetadata === "object" && m.sourceMetadata !== null ? m.sourceMetadata : undefined
+    };
+};
+export const loadOfflineManifestForModel = (cacheDir, model) => {
+    const modelCacheDir = join(cacheDir, ...model.split("/"));
+    const manifestPath = join(modelCacheDir, "manifest.json");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Manifest file not found: ${manifestPath}`);
+    }
+    try {
+        const rawContent = readFileSync(manifestPath, "utf8");
+        const manifestJson = JSON.parse(rawContent);
+        return validateOfflineManifest(manifestJson, modelCacheDir);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load or validate manifest at ${manifestPath}: ${msg}`);
+    }
+};
+export const importOfflineAssetPack = async (packDir, cacheDir) => {
+    const manifestPath = join(packDir, "manifest.json");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Asset pack missing manifest.json at ${packDir}`);
+    }
+    // Read and validate the manifest in the staging/pack directory
+    let manifest;
+    try {
+        const rawContent = readFileSync(manifestPath, "utf8");
+        const manifestJson = JSON.parse(rawContent);
+        manifest = validateOfflineManifest(manifestJson, packDir);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Import failed during manifest validation: ${msg}`);
+    }
+    const targetModelDir = join(cacheDir, ...manifest.modelId.split("/"));
+    mkdirSync(targetModelDir, { recursive: true });
+    // Copy manifest.json
+    copyFileSync(manifestPath, join(targetModelDir, "manifest.json"));
+    // Copy all assets
+    for (const asset of Object.values(manifest.assets)) {
+        const sourcePath = join(packDir, asset.path);
+        const targetPath = join(targetModelDir, asset.path);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        copyFileSync(sourcePath, targetPath);
+    }
+    try {
+        const { clearLocalEmbeddingProviderCache } = await import("./local-provider.js");
+        const { clearEmbeddingRuntimeCaches } = await import("./embeddings.js");
+        clearLocalEmbeddingProviderCache();
+        clearEmbeddingRuntimeCaches();
+    }
+    catch {
+        // Gracefully handle dynamic import edge cases
+    }
+};
+export const exportOfflineAssetPack = async (cacheDir, model, targetPackDir) => {
+    // Load and validate from cache
+    const manifest = loadOfflineManifestForModel(cacheDir, model);
+    const modelCacheDir = join(cacheDir, ...model.split("/"));
+    mkdirSync(targetPackDir, { recursive: true });
+    // Copy manifest.json
+    copyFileSync(join(modelCacheDir, "manifest.json"), join(targetPackDir, "manifest.json"));
+    // Copy all assets
+    for (const asset of Object.values(manifest.assets)) {
+        const sourcePath = join(modelCacheDir, asset.path);
+        const targetPath = join(targetPackDir, asset.path);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        copyFileSync(sourcePath, targetPath);
+    }
+};
+//# sourceMappingURL=offline-manifest.js.map

package/dist/store/vector/offline-manifest.js.map

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

package/dist/store/vector/provider-types.d.ts

@@ -3,6 +3,7 @@ export type SemanticEmbeddingProvider = {
     model: string;
     version: string;
     dimensions: number;
+    manifestId?: string;
     embedQuery(text: string): Promise<number[]>;
     embedPassage(text: string): Promise<number[]>;
 };

package/dist/types/domain.d.ts

@@ -1,7 +1,7 @@
 export type TaskType = "bug_fix" | "build_debug" | "config_debug" | "test_debug" | "integration_fix" | "feature_add" | "refactor" | "performance" | "general";
 export type ResolvedTaskType = TaskType | "unknown";
 export type ExperienceState = "candidate" | "priority_candidate" | "active" | "cooling" | "retired";
-export type DeliveryState = "shadow_only" | "conservative_only" | "eligible" | "quarantined";
+export type DeliveryState = "shadow_only" | "conservative_only" | "eligible" | "quarantined" | "shadow_probe" | "retired";
 export type ExperienceNodeType = "strategy" | "warning";
 export type PromotionSignal = "normal" | "high_value";
 export type MergeAction = "ADD" | "UPDATE" | "NONE";
@@ -88,6 +88,7 @@ export type RetrievalContext = {
     isReadOnly?: boolean;
     modulePaths?: string[];
     expectationCorrectionIntent?: boolean;
+    db?: any;
 };
 export type RetrievalPolicyStageName = "retrieval_context" | "hard_filter" | "shortlist" | "semantic_rerank_backfill" | "policy_enrichment" | "decision_assembly";
 export type RetrievalPolicyStageDiagnostic = {
@@ -245,6 +246,24 @@ export type ExperienceNode = {
     last_harmed_at?: string;
     quarantined_at?: string;
     quarantine_reason?: string;
+    embedding_manifest_id?: string;
+    migration_status?: 'current' | 'pending' | 'migrating' | 'failed';
+    migration_last_error?: string;
+    migration_updated_at?: string;
+    source_fingerprint_hash?: string;
+    portable_validation_evidence?: {
+        compatibilityClasses: Record<string, {
+            successReuseCount: number;
+            harmCount: number;
+            lastUsedAt: number;
+        }>;
+    };
+    quarantine_lease_expires_at?: string;
+    quarantine_original_delivery_state?: DeliveryState;
+    quarantine_release_attempt_count?: number;
+    quarantine_last_release_attempt_at?: string;
+    quarantine_release_reason?: string;
+    quarantine_no_harm_pass_count?: number;
     created_at: string;
     updated_at: string;
 };
@@ -283,6 +302,11 @@ export type AttributionRecord = {
     user_override?: "helped" | "harmed" | "neutral";
     source: AttributionSource;
     attribution_reason?: FeedbackAttributionReason | "manual_override" | "diagnostic_record";
+    trajectory_verdict?: string;
+    trajectory_confidence?: string;
+    trajectory_matched_expectations?: string[];
+    trajectory_violated_expectations?: string[];
+    trajectory_evidence_refs?: string[];
     created_at: string;
     resolved_at?: string;
 };
@@ -336,6 +360,7 @@ export type InjectionScorecardNode = {
 export type InjectionScorecardCandidate = {
     id: string;
     matchScorecard?: MatchScorecard;
+    portabilityScorecard?: PortabilityScorecard;
     semanticScore?: number;
     lexicalScore?: number;
     fusedScore?: number;
@@ -514,3 +539,88 @@ export type DistillationJob = {
     finished_at?: string;
     discarded_at?: string;
 };
+export type ProjectFingerprint = {
+    schemaVersion: string;
+    fingerprintHash: string;
+    timestamp: number;
+    primaryLanguage: string;
+    packageManager: string;
+    lockfileFamily: string;
+    frameworks: Record<string, number>;
+    databaseOrORM: Record<string, number>;
+    testBuildTools: Record<string, number>;
+    hostRuntimeAdapters: Record<string, number>;
+    configMarkers: string[];
+    workspaceRootPath?: string;
+    projectRootScopeId?: string;
+};
+export type ScopeFingerprint = {
+    scope_id: string;
+    schema_version: string;
+    fingerprint_hash: string;
+    fingerprint_json: string;
+    created_at: string;
+    updated_at: string;
+};
+export type OfflineAssetManifest = {
+    id?: string;
+    manifestVersion: string;
+    providerId: string;
+    modelId: string;
+    dimensions: number;
+    preprocessingVersion: string;
+    assets: Record<string, {
+        path: string;
+        sha256: string;
+    }>;
+    license?: string;
+    sourceMetadata?: Record<string, unknown>;
+};
+export type PortabilityBand = "incompatible" | "weakly_related" | "same_family" | "validated_portable";
+export type PortabilityScorecard = {
+    portabilityBand: PortabilityBand;
+    score: number;
+    matchedLanguage: boolean;
+    sharedDependencies: string[];
+    penalties: Array<{
+        dependency: string;
+        category: string;
+        penalty: number;
+        reason: string;
+    }>;
+    negativeEvidence: string[];
+    whyScore: string;
+    successReuseCount?: number;
+    harmCount?: number;
+};
+export type TrajectoryExpectationType = "recommend" | "avoid";
+export type ExpectationActionType = "command" | "artifact" | "generic";
+export type TrajectoryExpectation = {
+    id: string;
+    type: TrajectoryExpectationType;
+    actionType: ExpectationActionType;
+    toolNamePattern?: string;
+    commandPattern?: string;
+    artifactPattern?: string;
+    artifactAction?: "read" | "write" | "any";
+    originalStep: string;
+    ordered: boolean;
+    sourceField?: "recommended_steps" | "avoid_steps" | "success_signal" | "stop_condition" | "escalation_condition";
+    requiredForAdoption?: boolean;
+};
+export type CompiledTrajectoryExpectations = {
+    orderedExpectations: TrajectoryExpectation[];
+    unorderedExpectations: TrajectoryExpectation[];
+};
+export type NormalizedToolEvent = {
+    toolName: string;
+    commandFamily?: string;
+    subcommand?: string;
+    normalizedInput?: string;
+    normalizedOutput?: string;
+    artifactExtension?: string;
+    artifactName?: string;
+    artifactPath?: string;
+    artifactPaths?: string[];
+    status: "success" | "failure" | "unknown";
+};

package/dist/types/plugin.d.ts

@@ -8,6 +8,7 @@ export type HostPromptContext = {
     taskSummary?: string;
     contextSummary?: string;
     injectedNodeIds?: string[];
+    outcomeSignal?: string;
 };
 export type HostToolResult = {
     sessionId?: string;

package/docs/releases/v0.4.0.md

@@ -0,0 +1,39 @@
+# ExperienceEngine v0.4.0
+
+`v0.4.0` introduces the **Governed Portable Experience** layer, enabling safe cross-repository experience sharing, stack-aware compatibility fingerprinting, causal trajectory-based attribution, and a lease-based quarantine and shadow-probe lifecycle.
+
+## What Changed
+
+- **Offline Embedding Profiles**: Added support for `standard`, `local-download`, and `strict-offline` embedding profile configurations, backed by a strict offline asset manifest registry that validates checksums and licenses.
+- **Compatibility Fingerprints**: Implemented deterministic fingerprint extraction for repository scopes, capturing primary languages, frameworks, ORMs, and lockfile-resolved (npm, pnpm, yarn) dependency major versions, with monorepo workspace package support.
+- **Portability Scoring and Bands**: Created a scorecard combining fingerprint, path, and task family similarity with prior reuse evidence. Classifies cross-repo candidates into portability bands (`validated_portable`, `same_family`, `weakly_related`, `incompatible`) with strict framework SemVer major-version penalties.
+- **Cross-Repository Intervention Governance**: Enabled progressive delivery where `same_family` candidates are limited to conservative prompt delivery, `weakly_related` remain record-only, and `incompatible` are skipped.
+- **Causal Trajectory Attribution**: Built a compiler that normalizes tool names/arguments and redacts volatile tokens (temp paths, UUIDs, branch names) to check timelines against compiled expectations (`recommended_steps` and `avoid_steps`). Yields detailed verdicts (`adoption_detected`, `non_adoption_detected`, `contra_adoption_detected`, etc.).
+- **Quarantine Shadow-Probe Lifecycle**: Expired quarantine leases now transition candidates to a `shadow_probe` state. These are withheld from live prompt injection but evaluated as diagnostic candidates, restoring to `conservative` only after accumulating bounded no-harm passes in matching tasks, or retiring/re-quarantining on repeated harm.
+- **Enhanced Diagnostics and Operator Surfaces**:
+  - Extended `ee doctor` to report embedding profile type, manifest checksum health, and offline asset readiness.
+  - Extended `ee inspect` with verbose output showing compatibility fingerprint summaries, SemVer penalties, causal trajectory verdicts with matched/violated expectations, and quarantine lease/shadow-probe histories.
+  - Updated README, README.zh-CN, and `docs/user-guide.md` with complete architecture and operator documentation.
+
+## Boundaries
+
+- **No Blind Cross-Repo Injection**: Tech-stack similarity alone never unlocks direct eligible prompt injection for cross-repo candidates.
+- **Strict Shadow-Probe Isolation**: Shadow-probe nodes remain completely excluded from live prompt injection; they accumulate no-harm passes solely via record-only diagnostic evaluations.
+- **Avoid-Step Defaults**: Avoid-step violations default to non-adoption (`non_adoption_detected` or `contra_adoption_detected`) rather than automatically triggering a causal harm verdict, unless causal failure is explicitly observed.
+- **Offline Integrity**: Strict offline profiles fail loudly on missing or corrupt assets, preventing silent online fallbacks unless explicitly allowed.
+
+## Validation
+
+- Comprehensive unit and integration test coverage for embedding profiles, vector migration, fingerprinting, portability scoring, trajectory compilation, causal matches, quarantine leases, shadow-probes, and CLI diagnostics.
+- Validation checks completed successfully:
+  - `pnpm exec tsc --noEmit`
+  - `pnpm exec vitest run`
+  - `pnpm exec openspec validate add-governed-portable-experience --strict`
+  - `pnpm check`
+  - `npm pack --dry-run`
+- Real-host validation completed for:
+  - WSL Codex CLI lifecycle wrapper and persistence.
+  - Claude Code MCP wiring and `experienceengine_get_capabilities` tool invocation with `nvidia/nemotron-3-super-120b-a12b:free`.
+  - WSL OpenClaw plugin wiring after `ee repair openclaw`, with live high-confidence scenario writeback using `openrouter/nvidia/nemotron-3-super-120b-a12b:free`.
+- Known host boundary:
+  - Windows Codex App validation was blocked by the local WindowsApps `codex.exe` shim returning `EPERM` / `Access is denied`; WSL Codex CLI validation passed.

package/docs/user-guide.md

@@ -366,6 +366,40 @@ ee maintenance governance drain --cwd /path/to/repo
 
 That command is for explicit operator troubleshooting or catch-up. It uses the same scheduler, lease, validator, audit, and rollback snapshot path as host-attached governance. An optional keeper can wake the same drain path for stricter wall-clock schedules, but it does not bypass budgets, leases, deterministic validators, guarded execution rules, or rollback safeguards.
 
+## Governed Portable Experience
+
+ExperienceEngine connects retrieval, attribution, and lifecycle layers to support governed, cautious sharing of experience nodes across different repositories and scopes.
+
+### Portability Bands & SemVer Compatibility
+
+When retrieving experience candidates for a task, ExperienceEngine calculates a cross-repository compatibility scorecard. This scorecard determines how safe the guidance is in the current environment using the following **Portability Bands**:
+- `validated_portable`: Highly compatible. The node matches the local programming language, and any shared dependencies have verified SemVer compatibility.
+- `cautiously_portable`: Medium compatibility. Reused with caution, usually limited to conservative delivery state until local execution success is demonstrated.
+- `incompatible`: The node requires frameworks or languages not present in the current project. Delivery is blocked.
+
+Compatibility scoring factors in **SemVer matching penalties**:
+- Framework or dependency version mismatches subtract penalty points (e.g. minor or major version drift).
+- Language mismatches (e.g., trying to use Python guidance in a TypeScript codebase) flag the node as incompatible.
+
+### Causal Trajectory Attribution
+
+During post-task finalization, ExperienceEngine verifies if the host agent actually adopted the expectations of an injected hint. This **Causal Trajectory Attribution** produces a precise verdict:
+- `adoption_detected`: The agent successfully matched the expectations of the injected hint (e.g., specific file modifications or CLI tool executions).
+- `non_adoption_detected`: The agent completed the task but did not follow the suggested guidance.
+- `unverifiable`: The task ended in failure, or outcomes could not be traced clearly.
+
+These trajectory verdicts prevent false positives in outcome attribution, ensuring that helpfulness or harm is only counted if the agent actually used the guidance.
+
+### Quarantine Leases & Shadow-Probe Release
+
+To ensure quarantined nodes have a safe path back to eligibility without erasing historical lessons:
+1. **Quarantine Leases**: When a node is quarantined due to harm or invalidation, it is given a lease duration.
+2. **Lease Expiration**: Once the lease expires, the node is transitioned to a special `shadow_probe` delivery state.
+3. **Shadow Probe**: While in `shadow_probe`, the node is evaluated silently behind the scenes. If the agent finishes tasks using this guidance without any new harm, a **no-harm pass counter** is incremented.
+4. **Conservative Restoration**: Upon successfully passing the shadow probe, the node is restored to `conservative_only` delivery (rather than direct live eligibility).
+5. **Repeated-Harm Retirement**: If the node causes repeated harm during its shadow probe or live recovery, it is permanently retired.
+6. **Preservation of History**: Throughout this cycle, historical helped/harmed counts, original delivery states, and release attempt logs are strictly preserved.
+
 ## How MCP Interaction Works
 
 For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
@@ -531,6 +565,13 @@ Notes:
 - the recommended registry for managed model downloads is `https://registry.npmjs.org`
 - `ee doctor ...` reports a first-value readiness summary so users can see how much captured evidence exists before the first durable node is promoted
 
+### Offline Profiles, Manifest Health, and Vector Migration
+
+For air-gapped or sensitive environments, ExperienceEngine supports fully offline semantic retrieval:
+- **Offline Profiles**: Set `embeddingProvider = "local"` and configure an offline profile (such as `strict-offline`) in settings. ExperienceEngine will rely entirely on local ONNX model assets.
+- **Manifest Health Verification**: When running `ee doctor`, the system validates the health of the local offline profile. It reads the model manifest files, checks checksums, and detects corrupted assets. If a strict-offline profile is active but files are missing or corrupt, a warning is raised automatically.
+- **Vector Migration**: Upgrading embedding models or altering dimensions requires vector migration. ExperienceEngine tracks vector migration status for every node (`migrated`, `pending`, etc.) along with timestamps and migration errors. You can inspect this status via `ee inspect node:<id>` or `ee doctor`.
+
 Maintenance:
 
 ```bash

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "experienceengine",
   "name": "ExperienceEngine",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Context-aware experience intervention controller for coding and debugging tasks.",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alan512/experienceengine",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",