ds4-context-engine 0.1.1 → 0.2.0-beta.1

package/src/extension/commands.ts

@@ -12,6 +12,7 @@ import type {
 const NUMBER_FORMAT = new Intl.NumberFormat("en-US");
 const SUBCOMMANDS = [
   "status",
+  "adapter",
   "tokens",
   "manifest",
   "explain",
@@ -26,6 +27,8 @@ const SUBCOMMANDS = [
   "memory",
   "privacy",
   "model",
+  "quality",
+  "ranking",
   "continuation",
   "artifacts",
   "compaction",
@@ -154,6 +157,8 @@ function formatStatus(diagnostics: RuntimeDiagnostics): string {
     `State:                    ${diagnostics.phase}`,
     `Planner:                  ${diagnostics.plannerVersion} (${diagnostics.lastManifest?.planning?.mode ?? diagnostics.contextMode})`,
     `Extension / Pi target:    ${diagnostics.extensionVersion} / ${diagnostics.supportedPiVersion}`,
+    `Adapter contract:         ${diagnostics.adapter.contractVersion}`,
+    `Adapter capabilities:     ${diagnostics.adapter.enabled.length} enabled / ${diagnostics.adapter.disabled.length} disabled`,
     `Session:                  ${session?.sessionId ?? "unavailable"}`,
     `Session entries:          ${count(session?.totalEntries)}`,
     `Current branch entries:   ${count(session?.branchEntries)}`,
@@ -182,6 +187,8 @@ function formatStatus(diagnostics: RuntimeDiagnostics): string {
     `Calibration samples:       ${count(diagnostics.modelAwareness?.calibration.acceptedSamples)} accepted`,
     `Native continuation:       ${diagnostics.nativeContinuation.status} (${diagnostics.nativeContinuation.last?.mode ?? "no request"})`,
     `Continuation saved items:  ${count(diagnostics.nativeContinuation.last?.omittedInputItems)}`,
+    `Quality metrics:           ${diagnostics.quality.enabled ? `${count(diagnostics.quality.storedSamples)} sample(s)` : "disabled"}`,
+    `Learned ranking:           ${diagnostics.ranking.status} (${diagnostics.ranking.modelLoaded ? diagnostics.ranking.modelId ?? "loaded" : "no model"})`,
     `Artifact offload:          ${count(diagnostics.artifacts.offloadedCount)} result(s), ${count(diagnostics.artifacts.offloadedBytes)} bytes`,
     `Artifact tokens saved:     ${count(diagnostics.artifacts.estimatedTokensSaved)} estimated`,
     `Artifact objects / refs:   ${count(diagnostics.artifacts.stats.objects)} / ${count(diagnostics.artifacts.stats.references)}`,
@@ -365,6 +372,12 @@ function formatRetrieved(diagnostics: RuntimeDiagnostics): string {
     `Status:                   ${retrieval.status}`,
     `Query terms:              ${retrieval.queryTerms.length > 0 ? retrieval.queryTerms.join(", ") : "none"}`,
     `Candidates:               ${count(retrieval.candidateCount)}`,
+    `Lexical / vector / fused: ${count(retrieval.semantic.lexicalCandidates)} / ${count(retrieval.semantic.vectorCandidates)} / ${count(retrieval.semantic.fusedCandidates)}`,
+    `Embedding model:          ${retrieval.semantic.provider && retrieval.semantic.model ? `${retrieval.semantic.provider}/${retrieval.semantic.model}` : "disabled"}`,
+    `Embedding dimensions/mode:${count(retrieval.semantic.dimensions).padStart(9)} / ${retrieval.semantic.destination ?? "n/a"}`,
+    `Vector index/cache hit:   ${retrieval.semantic.indexFresh ? "fresh" : "stale/unavailable"} / ${retrieval.semantic.queryCacheHit ? "yes" : "no"}`,
+    `Embedding calls source/query:${count(retrieval.semantic.sourceEmbeddingCalls).padStart(6)} / ${count(retrieval.semantic.queryEmbeddingCalls)}`,
+    ...(retrieval.semantic.fallbackReason ? [`Semantic fallback:        ${retrieval.semantic.fallbackReason}`] : []),
     `Alternate-branch blocked:${count(retrieval.alternateBranchCandidates).padStart(9)}`,
     `Duplicate candidates:     ${count(retrieval.duplicateCandidates)}`,
     `Planner exclusions:       ${count(retrieval.plannerExcludedCount)}`,
@@ -404,6 +417,11 @@ function formatProject(diagnostics: RuntimeDiagnostics): string {
     `Skipped large/binary/secret:${count(sync?.skippedLarge).padStart(7)} / ${count(sync?.skippedBinary)} / ${count(sync?.skippedSensitive)}`,
     `Query terms:               ${project.queryTerms.length > 0 ? project.queryTerms.join(", ") : "none"}`,
     `Candidates / duplicates:   ${count(project.candidateCount)} / ${count(project.duplicateCandidates)}`,
+    `Lexical / vector / fused:  ${count(project.semantic.lexicalCandidates)} / ${count(project.semantic.vectorCandidates)} / ${count(project.semantic.fusedCandidates)}`,
+    `Embedding model:           ${project.semantic.provider && project.semantic.model ? `${project.semantic.provider}/${project.semantic.model}` : "disabled"}`,
+    `Embedding dimensions/mode: ${count(project.semantic.dimensions)} / ${project.semantic.destination ?? "n/a"}`,
+    `Vector index/cache hit:    ${project.semantic.indexFresh ? "fresh" : "stale/unavailable"} / ${project.semantic.queryCacheHit ? "yes" : "no"}`,
+    ...(project.semantic.fallbackReason ? [`Semantic fallback:         ${project.semantic.fallbackReason}`] : []),
     `Invalidated / reindexed:   ${count(project.invalidatedSnippets)} / ${count(project.reindexedFiles)}`,
     `Planner exclusions:        ${count(project.plannerExcludedCount)}`,
     `Selected / maximum tokens: ${count(project.selectedTokens)} / ${count(project.maxTokens)}`,
@@ -449,6 +467,7 @@ function formatMemory(runtime: Ds4ContextRuntime, diagnostics: RuntimeDiagnostic
     `Active / inactive:        ${count(diagnostics.memory.activeMemories)} / ${count(diagnostics.memory.inactiveMemories)}`,
     `Selected / excluded:      ${count(diagnostics.memory.selectedMemories.length)} / ${count(diagnostics.memory.excludedMemories)}`,
     `Selected tokens:          ${count(diagnostics.memory.selectedMemoryTokens)}`,
+    `Cross-session:            ${diagnostics.memory.crossSession.status} (${count(diagnostics.memory.crossSession.contributingSessions)} contributing / ${count(diagnostics.memory.crossSession.discoveredSessions)} discovered)`,
     ...diagnostics.memory.warnings.map((warning) => `Warning:                  ${warning}`),
     "",
     ...(memories.length === 0
@@ -463,6 +482,33 @@ function formatMemory(runtime: Ds4ContextRuntime, diagnostics: RuntimeDiagnostic
     "Add: /context memory add [--scope session|project] [--classification LEVEL] [--key KEY] [--source ID,ID] <claim>",
     "Replace: /context memory supersede MEMORY_ID [--classification LEVEL] [--source ID,ID] <new claim>",
     "Invalidate/expire: /context memory invalidate|expire MEMORY_ID [reason]",
+    "Sources: /context memory sources|exclude SESSION_ID [reason]|include SESSION_ID",
+  ].join("\n");
+}
+
+function formatProjectMemorySources(runtime: Ds4ContextRuntime, diagnostics: RuntimeDiagnostics): string {
+  const cross = diagnostics.memory.crossSession;
+  const sources = runtime.projectMemorySources();
+  return [
+    "DS4 Cross-Session Project Memory Sources",
+    "",
+    `Enabled / status:         ${cross.enabled ? "yes" : "no"} / ${cross.status}`,
+    `Discovered / contributing:${count(cross.discoveredSessions).padStart(8)} / ${count(cross.contributingSessions)}`,
+    `Excluded / unavailable:  ${count(cross.excludedSessions).padStart(8)} / ${count(cross.unavailableSessions)}`,
+    `Incremental / rebuilt:   ${count(cross.incrementalSessions).padStart(8)} / ${count(cross.rebuiltSessions)}`,
+    ...cross.warnings.map((warning) => `Warning:                  ${warning}`),
+    "",
+    ...(sources.length === 0
+      ? ["No project memory source sessions have been discovered."]
+      : sources.map((source, index) => [
+          `${index + 1}. ${source.sessionId}  ${source.status}  mutations=${count(source.indexedMutations)} active=${count(source.activeProjectMemories + source.activeProjectPins)}`,
+          `   records=${count(source.indexedRecords)} malformed=${count(source.malformedLines)} file=${JSON.stringify(source.sessionFile)}`,
+          ...(source.exclusionReason ? [`   exclusion: ${source.exclusionReason}`] : []),
+          ...(source.lastError ? [`   error: ${source.lastError}`] : []),
+        ].join("\n"))),
+    "",
+    "Exclude: /context memory exclude SESSION_ID [reason]",
+    "Restore: /context memory include SESSION_ID",
   ].join("\n");
 }
 
@@ -528,6 +574,71 @@ function formatModelAwareness(diagnostics: RuntimeDiagnostics): string {
   ].join("\n");
 }
 
+function formatQuality(diagnostics: RuntimeDiagnostics): string {
+  const quality = diagnostics.quality;
+  const aggregate = quality.aggregate;
+  const percentage = (rate: number | null): string => rate === null ? "n/a" : `${(rate * 100).toFixed(2)}%`;
+  const reasonSummary = (reasons: Readonly<Record<string, number>>): string => {
+    const entries = Object.entries(reasons);
+    return entries.length > 0
+      ? entries.map(([reason, total]) => `${reason}=${count(total)}`).join(", ")
+      : "none";
+  };
+  const budgetLines = Object.entries(aggregate.budgetUtilization).map(([kind, budget]) =>
+    `  ${kind.padEnd(12)} ${count(budget.selectedTokens)} / ${count(budget.limitTokens)} (${(budget.utilization * 100).toFixed(2)}%), dropped ${count(budget.droppedTokens)}`
+  );
+  return [
+    "DS4 Context Quality",
+    "",
+    `Status:                    ${quality.enabled ? "enabled" : "disabled (opt-in)"}`,
+    `Metrics version:           ${quality.metricsVersion}`,
+    `Samples stored/labeled:    ${count(quality.storedSamples)} / ${count(aggregate.labeledSampleCount)}`,
+    `Corrupt samples ignored:   ${count(quality.ignoredSamples)}`,
+    `Primary quality score:     ${(aggregate.qualityScore * 100).toFixed(2)}%`,
+    `Evidence recall:           ${percentage(aggregate.evidenceRecall.rate)} (${count(aggregate.evidenceRecall.numerator)}/${count(aggregate.evidenceRecall.denominator)})`,
+    `Irrelevant-token ratio:    ${percentage(aggregate.irrelevantTokenRatio.rate)}`,
+    `Duplicate references:      ${count(aggregate.duplicateEvidence.duplicateReferences)} / ${count(aggregate.duplicateEvidence.selectedReferences)}`,
+    `Provenance coverage:       ${percentage(aggregate.provenanceCoverage.rate)}`,
+    `Current request retained:  ${percentage(aggregate.currentRequestRetention.rate)}`,
+    `Atomic groups valid:       ${percentage(aggregate.atomicGroupValidity.rate)}`,
+    `Overflow / fallback rate:  ${percentage(aggregate.overflowRate.rate)} / ${percentage(aggregate.fallbackRate.rate)}`,
+    `Selected / dropped tokens: ${count(aggregate.selectedTokens)} / ${count(aggregate.droppedTokens)}`,
+    `Planning mean / p95:       ${quality.timing.meanPlanningDurationMs === undefined ? "n/a" : `${quality.timing.meanPlanningDurationMs.toFixed(3)} ms`} / ${quality.timing.p95PlanningDurationMs === undefined ? "n/a" : `${quality.timing.p95PlanningDurationMs.toFixed(3)} ms`}`,
+    "Category budget utilization:",
+    ...(budgetLines.length > 0 ? budgetLines : ["  no samples"]),
+    `Selection reasons:         ${reasonSummary(aggregate.selectionReasons)}`,
+    `Drop reasons:              ${reasonSummary(aggregate.dropReasons)}`,
+    ...(quality.lastError ? [`Last quality warning:       ${quality.lastError}`] : []),
+    "",
+    "Quality storage contains counts, versions, labels and timings only; prompt and evidence text are never persisted.",
+  ].join("\n");
+}
+
+function formatRanking(diagnostics: RuntimeDiagnostics): string {
+  const ranking = diagnostics.ranking;
+  return [
+    "DS4 Learned Ranking",
+    "",
+    `Mode / status:             ${ranking.mode} / ${ranking.status}`,
+    `Feature schema:            ${ranking.featureVersion}`,
+    `Model:                     ${ranking.modelId ?? "unavailable"}`,
+    `Model path:                ${ranking.modelPath ?? "unavailable"}`,
+    `Loaded / promoted:         ${ranking.modelLoaded ? "yes" : "no"} / ${ranking.promoted ? "yes" : "no"}`,
+    `Training samples:          ${count(ranking.trainingSamples)}`,
+    `Malformed / duplicate:     ${count(ranking.malformedFeedback)} / ${count(ranking.duplicateFeedback)}`,
+    `Latest candidates:         ${count(ranking.candidateCount)}`,
+    `Top changed in shadow:     ${ranking.topChanged ? "yes" : "no"}`,
+    `Pairwise disagreements:    ${count(ranking.pairwiseDisagreements)}`,
+    `Mean rank shift:           ${ranking.meanRankShift.toFixed(6)}`,
+    `Inference duration:        ${ranking.durationMs.toFixed(3)} ms`,
+    ...(ranking.fallbackReason ? [`Static fallback:            ${ranking.fallbackReason}`] : []),
+    ...ranking.warnings.map((warning) => `Warning:                    ${warning}`),
+    "",
+    "Feedback stores only bounded numeric features, hashes, label, version, and classification in Pi JSONL.",
+    "Shadow mode records aggregate comparison only and never changes selected context.",
+  ].join("\n");
+}
+
 function formatNativeContinuation(diagnostics: RuntimeDiagnostics): string {
   const continuation = diagnostics.nativeContinuation;
   const latest = continuation.last;
@@ -585,6 +696,27 @@ function formatArtifacts(diagnostics: RuntimeDiagnostics): string {
   ].join("\n");
 }
 
+function formatAdapter(diagnostics: RuntimeDiagnostics): string {
+  const negotiation = diagnostics.adapter;
+  return [
+    "DS4 Runtime Adapter",
+    "",
+    `Runtime:             Pi`,
+    `Contract:            ${negotiation.contractVersion}`,
+    `Enabled requested:   ${count(negotiation.enabled.length)}`,
+    `Disabled requested:  ${count(negotiation.disabled.length)}`,
+    "",
+    ...negotiation.statuses.map((status) =>
+      `${status.id}: ${status.supported ? `supported (${status.version ?? "unversioned"})` : `unavailable (${status.reason ?? "no reason"})`}; ${status.enabled ? "enabled" : status.requested ? "disabled safely" : "not requested"}`
+    ),
+    ...(negotiation.diagnostics.length > 0
+      ? ["", ...negotiation.diagnostics.map((diagnostic) =>
+          `${diagnostic.severity.toUpperCase()} ${diagnostic.code}: ${diagnostic.message}`
+        )]
+      : []),
+  ].join("\n");
+}
+
 function formatCompaction(diagnostics: RuntimeDiagnostics, preview: boolean): string {
   const compaction = diagnostics.compaction;
   return [
@@ -632,6 +764,11 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
           return;
         }
 
+        if (subcommand === "adapter") {
+          present(ctx, formatAdapter(runtime.diagnostics(ctx)));
+          return;
+        }
+
         if (subcommand === "tokens") {
           present(ctx, formatTokens(runtime.diagnostics(ctx)));
           return;
@@ -716,7 +853,27 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
             present(ctx, formatMemory(runtime, runtime.diagnostics(ctx)));
             return;
           }
+          if (nested.command === "sources") {
+            present(ctx, formatProjectMemorySources(runtime, runtime.diagnostics(ctx)));
+            return;
+          }
           const parsed = parseCommandArgs(nested.args);
+          if (nested.command === "exclude" || nested.command === "include") {
+            assertOptions(parsed.options, []);
+            const sessionId = parsed.positionals[0];
+            if (!sessionId) {
+              throw new Error(`Usage: /context memory ${nested.command} SESSION_ID${nested.command === "exclude" ? " [reason]" : ""}`);
+            }
+            runtime.setProjectMemorySourceExcluded(
+              sessionId,
+              nested.command === "exclude",
+              nested.command === "exclude"
+                ? parsed.positionals.slice(1).join(" ") || undefined
+                : undefined,
+            );
+            present(ctx, `Project memory source ${sessionId} ${nested.command === "exclude" ? "excluded" : "restored"}`);
+            return;
+          }
           if (nested.command === "add") {
             assertOptions(parsed.options, ["scope", "key", "source", "classification"]);
             const scope = (parsed.options.get("scope") ?? "session").toLowerCase();
@@ -769,7 +926,7 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
             present(ctx, `Memory ${memory.id} is ${memory.status}`);
             return;
           }
-          throw new Error("Usage: /context memory [list|add|supersede|invalidate|expire]");
+          throw new Error("Usage: /context memory [list|sources|exclude|include|add|supersede|invalidate|expire]");
         }
 
         if (subcommand === "privacy") {
@@ -782,6 +939,55 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
           return;
         }
 
+        if (subcommand === "quality") {
+          present(ctx, formatQuality(runtime.diagnostics(ctx)));
+          return;
+        }
+
+        if (subcommand === "ranking") {
+          const nested = splitCommand(subcommandArgs, "status");
+          if (nested.command === "status") {
+            if (nested.args.trim()) throw new Error("Usage: /context ranking [status|feedback|train]");
+            present(ctx, formatRanking(runtime.diagnostics(ctx)));
+            return;
+          }
+          if (nested.command === "feedback") {
+            const parsed = parseCommandArgs(nested.args);
+            assertOptions(parsed.options, ["classification"]);
+            const label = parsed.positionals[0];
+            const candidateId = parsed.positionals[1];
+            if ((label !== "useful" && label !== "irrelevant") || !candidateId || parsed.positionals.length !== 2) {
+              throw new Error("Usage: /context ranking feedback useful|irrelevant CANDIDATE_ID [--classification CLASS]");
+            }
+            const feedback = runtime.recordRankingFeedback(
+              candidateId,
+              label,
+              classificationOption(parsed.options.get("classification")),
+              ctx,
+              (customType, data) => pi.appendEntry(customType, data),
+            );
+            present(ctx, `Ranking feedback ${feedback.feedbackId} recorded as ${feedback.label} (${feedback.classification})`);
+            return;
+          }
+          if (nested.command === "train") {
+            if (nested.args.trim()) throw new Error("Usage: /context ranking train");
+            await ctx.waitForIdle();
+            const result = runtime.trainRankingModel(ctx);
+            present(ctx, [
+              "DS4 Ranking Model Trained",
+              "",
+              `Model:              ${result.modelId}`,
+              `Samples:            ${count(result.sampleCount)} (${count(result.positiveSamples)} useful / ${count(result.negativeSamples)} irrelevant)`,
+              `Repositories:       ${count(result.repositoryCount)}`,
+              `Artifact:           ${result.modelPath}`,
+              ...(result.warnings.length > 0 ? [`Warnings:           ${result.warnings.length}`] : []),
+              "Active mode remains gated until held-out promotion succeeds.",
+            ].join("\n"));
+            return;
+          }
+          throw new Error("Usage: /context ranking [status|feedback|train]");
+        }
+
         if (subcommand === "continuation") {
           present(ctx, formatNativeContinuation(runtime.diagnostics(ctx)));
           return;
@@ -836,6 +1042,9 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
             && diagnostics.memory.warnings.length === 0
             && diagnostics.privacy.warnings.length === 0
             && diagnostics.nativeContinuation.warnings.length === 0
+            && diagnostics.quality.ignoredSamples === 0
+            && diagnostics.quality.lastError === undefined
+            && diagnostics.ranking.warnings.length === 0
             && artifactIntegrityIssues === 0
             && diagnostics.artifacts.warnings.length === 0;
           present(
@@ -854,6 +1063,9 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
               `Privacy enforcement:  ${diagnostics.privacy.enforcement}`,
               `Privacy warnings:     ${count(diagnostics.privacy.warnings.length)}`,
               `Continuation warnings: ${count(diagnostics.nativeContinuation.warnings.length)}`,
+              `Quality samples/ignored: ${count(diagnostics.quality.storedSamples)} / ${count(diagnostics.quality.ignoredSamples)}`,
+              `Quality warning:         ${diagnostics.quality.lastError ?? "none"}`,
+              `Ranking status/warnings:  ${diagnostics.ranking.status} / ${count(diagnostics.ranking.warnings.length)}`,
               `Artifact missing/corrupt: ${count(diagnostics.artifacts.stats.missing)} / ${count(diagnostics.artifacts.stats.corrupt)}`,
               `Artifact warnings:     ${count(diagnostics.artifacts.warnings.length)}`,
             ].join("\n"),

package/src/extension/index.ts

@@ -22,6 +22,7 @@ export function registerDs4ContextEngine(
     ...(dependencies.now ? { now: dependencies.now } : {}),
     ...(dependencies.idGenerator ? { idGenerator: dependencies.idGenerator } : {}),
     ...(dependencies.logSink ? { logSink: dependencies.logSink } : {}),
+    ...(dependencies.embeddingPort ? { embeddingPort: dependencies.embeddingPort } : {}),
   });
 
   const continuationStream = createOpenAIResponsesContinuationStream({