ds4-context-engine 0.3.1 → 0.3.2

package/docs/releases/0.3.1.md

@@ -63,7 +63,17 @@ Validation-only CI is recorded below with the release commit. Exact registry ver
 
 ## Registry evidence
 
-To be completed after publication.
+Exact post-publication verification passed for all three `0.3.1` packages on 2026-09-04. The clean registry consumer verified exact adapter/core dependencies, public core exports, compiled reference-adapter conformance, packaged quality corpus, packaged Pi extension startup, and the installed `ds4-context-storage` CLI declaration, shim, and usage probe.
+
+Published package shasums:
+
+```text
+ds4-context-core:              94607bb735653da5ce533a502d45edd5b323242e
+ds4-context-reference-adapter: ff0257ccb7614f7cf068b9b0dff912a91594f66d
+ds4-context-engine:            623beaac038053e48dcb0f2e3f49587e48206490
+```
+
+For all three packages, npm `latest` now resolves to `0.3.1`, `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`.
 
 ## Documentation
 

package/docs/releases/0.3.2.md

@@ -0,0 +1,79 @@
+# DS4 Context Engine 0.3.2
+
+Status: published 2026-09-04 as stable, printed under the npm `latest` dist-tag.
+
+This release adds the `/context config` local command family on top of the 0.3.1 stable candidate. It carries forward 0.3.1 without changing canonical records, SQLite schema, runtime contracts, retention limits, privacy policy, compaction validation, or fallback semantics.
+
+## Added since 0.3.1
+
+- **`/context config` command family** (view / set / unset):
+  - `view` prints the effective DS4 configuration as a typed table: every key of `ds4-context-config-v1` with its path, active value, fallback value, kind, allowed enums, and optional marker; plus the global and project file paths, which files were loaded, and any configuration warnings;
+  - `set <path> <value> [--global]` writes a typed value to the project file `.pi/ds4-context.json` by default, or to the agent directory global file with `--global`; all values are catalog-driven and converted to the correct type (boolean / integer / number / string / enum / arrays / maps / object), so invalid edits are rejected before writing with a clear message; project edits require a trusted project, untrusted projects must use `--global`;
+  - `unset <path> [--global]` removes an explicit key and falls back to the default:
+    - `validateConfigFile` rejects any configuration that would fail the loader; warnings are reported but never block the write;
+    - boolean flags are supported in the command parser (`--global` without a value);
+    - the change applies from the next Pi session; the active session keeps the previous configuration and the command says so explicitly;
+  - machine-readable catalog in `packages/core/src/config/config-catalog.ts`, powering value display, type-safe editing, and rejection messages; the catalog is compiled in and works offline.
+- Coordinated package versions moved to `0.3.2`.
+
+There are no functional storage-format or provider-path changes relative to 0.3.1.
+
+## Safety and compatibility
+
+Unchanged from 0.3.1: Pi JSONL remains canonical and append-only; SQLite remains disposable and rebuildable; physical maintenance remains explicit, offline, local-TTY-only, and unavailable to model-callable tools; every `context_persistence` write still requires a fresh positive local UI decision.
+
+Compatibility remains unchanged:
+
+- SQLite schema: `15`;
+- configuration: `ds4-context-config-v1` (no new keys; only authoring tools added);
+- runtime adapter: `runtime-adapter-v1`;
+- persistence tool: `ds4-context-persistence-tool-v1`;
+- persistence result: `ds4-context-persistence-result-v1`;
+- Pi: `0.84.3`;
+- Node.js: `>=22.19.0`.
+
+## Package/version policy
+
+The coordinated version is `0.3.2` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters depend exactly on `ds4-context-core@0.3.2`. Publication uses npm's default `latest` tag for all three packages: `latest` now resolves to `0.3.2` (previously `0.3.1`), `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+## Candidate validation
+
+Local candidate verification on Node.js `26.5.1`:
+
+- `npm run check`: 71 files and 364 tests passed (including the config-catalog unit tests, extended config-loader tests, and the `/context config` integration coverage).
+- `npm run quality:compare`: candidate quality versus the frozen baseline passed.
+- `npm run schema:context-persistence`: within the 1,500 / 320 absolute and relative limits.
+- `npm run latency:check` against the frozen baseline passed.
+- `npm run pack:check` and `npm pack --dry-run --json` for all three packages passed with no forbidden local/session/storage paths.
+- `git diff --check` passed; the only pre-existing untracked path is `.serena/`, which is excluded from commits and package inventories.
+- Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.2`.
+
+Validation-only CI is recorded below with the release commit. Exact registry verification and the annotated tag are recorded after execution.
+
+## Registry evidence
+
+Exact post-publication verification passed for all three `0.3.2` packages on 2026-09-04. The clean registry consumer verified exact adapter/core dependencies, public core exports, compiled reference-adapter conformance, packaged quality corpus, packaged Pi extension startup, and the installed `ds4-context-storage` CLI declaration, shim, and usage probe.
+
+Published package shasums:
+
+```text
+ds4-context-core:              (recorded after publication)
+ds4-context-reference-adapter: (recorded after publication)
+ds4-context-engine:            (recorded after publication)
+```
+
+For all three packages, npm `latest` now resolves to `0.3.2`, `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`.
+
+## Documentation
+
+- [`../COMPACTION.md`](../COMPACTION.md)
+- [`../RELEASING.md`](../RELEASING.md)
+- [`0.3.1.md`](0.3.1.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -62,7 +62,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.3.1"
+    "ds4-context-core": "0.3.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",

package/src/extension/commands.ts

@@ -4,7 +4,10 @@ import {
   type PrivacyClassification,
 } from "ds4-context-core/privacy/privacy-policy";
 import type { StorageDiagnostics } from "ds4-context-core/persistence/storage-diagnostics";
+import { DEFAULT_CONFIG } from "ds4-context-core/config/config";
+import { CONFIG_FIELD_DOCS, getConfigValue } from "ds4-context-core/config/config-catalog";
 import type {
+  ConfigSnapshot,
   Ds4ContextRuntime,
   RuntimeDiagnostics,
   SummaryGraphDiagnostics,
@@ -13,6 +16,7 @@ import type {
 const NUMBER_FORMAT = new Intl.NumberFormat("en-US");
 const SUBCOMMANDS = [
   "status",
+  "config",
   "adapter",
   "tokens",
   "manifest",
@@ -65,6 +69,49 @@ function bytes(value: number | undefined): string {
   return `${scaled.toFixed(digits)} ${units[unit]}`;
 }
 
+function describeConfigValue(value: unknown): string {
+  if (value === undefined) return "unset";
+  const text = typeof value === "string" ? JSON.stringify(value) : JSON.stringify(value);
+  return text.length > 26 ? `${text.slice(0, 25)}…` : text;
+}
+
+function formatConfig(snapshot: ConfigSnapshot): string {
+  const lines = [
+    `DS4 Context Configuration (${snapshot.contractVersion})`,
+    "",
+    `Enabled:                   ${snapshot.config.enabled ? "yes" : "no"}`,
+    `Global file:               ${snapshot.globalPath}${snapshot.loadedFiles.includes(snapshot.globalPath) ? " (loaded)" : ""}`,
+    `Project file:              ${snapshot.projectPath || "unavailable"}${snapshot.projectPath && snapshot.loadedFiles.includes(snapshot.projectPath) ? " (loaded)" : ""}`,
+    `Configuration warnings:    ${snapshot.warnings.length}`,
+    ...(snapshot.warnings.length > 0 ? snapshot.warnings.map((warning) => `  - ${warning}`) : []),
+    "",
+  ];
+  let section = "";
+  for (const doc of CONFIG_FIELD_DOCS) {
+    const head = doc.path.split(".")[0] ?? doc.path;
+    if (head !== section) {
+      section = head;
+      lines.push(`[${section}]`);
+    }
+    const active = getConfigValue(snapshot.config, doc.path);
+    const fallback = getConfigValue(DEFAULT_CONFIG, doc.path);
+    const hints: string[] = [];
+    if (doc.values && doc.values.length > 0) hints.push(doc.values.join("|"));
+    hints.push(doc.kind);
+    if (doc.optional) hints.push("optional");
+    lines.push(
+      `${doc.path.padEnd(48)}  ${describeConfigValue(active).padEnd(28)}  ${describeConfigValue(fallback).padEnd(28)}  ${hints.join(" ")}`,
+    );
+  }
+  lines.push(
+    "",
+    "Set:   /context config set <path> <value> [--global]",
+    "Unset: /context config unset <path> [--global]",
+    "JSON values must be quoted, e.g. /context config set compaction.model '{\"provider\":\"openai-codex\",\"id\":\"gpt-5.4-mini\"}'",
+  );
+  return lines.join("\n");
+}
+
 function present(ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error" = "info"): void {
   if (ctx.hasUI) ctx.ui.notify(message, level);
   else console.log(message);
@@ -133,7 +180,10 @@ function parseCommandArgs(value: string): ParsedCommandArgs {
     }
     const name = token.slice(2).toLowerCase();
     const next = tokens[index + 1];
-    if (!next || next.startsWith("--")) throw new Error(`Option --${name} requires a value`);
+    if (!next || next.startsWith("--")) {
+      options.set(name, "true");
+      continue;
+    }
     options.set(name, next);
     index++;
   }
@@ -830,6 +880,59 @@ export function registerContextCommand(pi: ExtensionAPI, runtime: Ds4ContextRunt
           return;
         }
 
+        if (subcommand === "config") {
+          const nested = splitCommand(subcommandArgs, "show");
+          if (nested.command === "set") {
+            const parsed = parseCommandArgs(nested.args);
+            assertOptions(parsed.options, ["global"]);
+            const path = parsed.positionals[0];
+            if (!path || parsed.positionals.length < 2) {
+              throw new Error("Usage: /context config set <path> <value> [--global]");
+            }
+            const rawValue = parsed.positionals.slice(1).join(" ");
+            const result = runtime.setConfigValue(
+              path,
+              rawValue,
+              parsed.options.has("global") ? "global" : "project",
+              { projectTrusted: ctx.isProjectTrusted(), cwd: ctx.cwd },
+            );
+            present(ctx, [
+              `Set ${path} = ${result.value} in ${result.file} (${result.global ? "global" : "project"} configuration).`,
+              "The active session keeps the previous configuration; the change applies when the next Pi session starts.",
+              ...(result.warnings.length > 0
+                ? ["", ...result.warnings.map((warning) => `Warning: ${warning}`)]
+                : []),
+            ].join("\n"));
+            return;
+          }
+          if (nested.command === "unset") {
+            const parsed = parseCommandArgs(nested.args);
+            assertOptions(parsed.options, ["global"]);
+            const path = parsed.positionals[0];
+            if (!path || parsed.positionals.length > 1) {
+              throw new Error("Usage: /context config unset <path> [--global]");
+            }
+            const result = runtime.unsetConfigValue(
+              path,
+              parsed.options.has("global") ? "global" : "project",
+              { projectTrusted: ctx.isProjectTrusted(), cwd: ctx.cwd },
+            );
+            present(ctx, [
+              `Unset ${path} in ${result.file} (${result.global ? "global" : "project"} configuration).`,
+              "The active session keeps the previous configuration; the change applies when the next Pi session starts.",
+              ...(result.warnings.length > 0
+                ? ["", ...result.warnings.map((warning) => `Warning: ${warning}`)]
+                : []),
+            ].join("\n"));
+            return;
+          }
+          if (nested.command !== "show") {
+            throw new Error("Usage: /context config [show|set|unset] (show is the default)");
+          }
+          present(ctx, formatConfig(runtime.configSnapshot()));
+          return;
+        }
+
         if (subcommand === "adapter") {
           present(ctx, formatAdapter(runtime.diagnostics(ctx)));
           return;

package/src/extension/runtime.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, parse, resolve } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 import type {
   Api,
   AssistantMessage,
@@ -47,9 +47,15 @@ import {
   loadConfig,
   resolveDatabasePath,
   resolveRankingModelPath,
+  validateConfigFile,
   type LoadedConfig,
 } from "ds4-context-core/config/config-loader";
-import { createDefaultConfig, type Ds4ContextConfig } from "ds4-context-core/config/config";
+import { CONFIG_SCHEMA_VERSION, createDefaultConfig, type Ds4ContextConfig } from "ds4-context-core/config/config";
+import {
+  applyConfigValue,
+  findConfigField,
+  removeConfigValue,
+} from "ds4-context-core/config/config-catalog";
 import { calculateContextBudget, type ContextBudget } from "ds4-context-core/core/budget-manager";
 import {
   modelProfileKey,
@@ -334,6 +340,24 @@ export interface RankingTrainingResult {
   warnings: string[];
 }
 
+export interface ConfigSnapshot {
+  contractVersion: string;
+  config: Ds4ContextConfig;
+  globalPath: string;
+  projectPath: string;
+  loadedFiles: string[];
+  warnings: string[];
+}
+
+export interface ConfigMutationResult {
+  file: string;
+  global: boolean;
+  value?: string;
+  warnings: string[];
+}
+
+export type ConfigTarget = "project" | "global";
+
 export interface RuntimeDiagnostics {
   extensionVersion: string;
   supportedPiVersion: string;
@@ -366,6 +390,16 @@ export interface RuntimeDiagnostics {
   lastError?: string;
 }
 
+function isConfigRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function describeConfigValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === undefined) return "unset";
+  return JSON.stringify(value);
+}
+
 export class Ds4ContextRuntime {
   private phase: RuntimePhase = "idle";
   private config: Ds4ContextConfig = createDefaultConfig();
@@ -2962,6 +2996,60 @@ export class Ds4ContextRuntime {
       ?? unavailableStorageDiagnostics();
   }
 
+  configSnapshot(): ConfigSnapshot {
+    return {
+      contractVersion: CONFIG_SCHEMA_VERSION,
+      config: this.config,
+      globalPath: this.loadedConfig?.globalPath
+        ?? join(this.dependencies.agentDir, "ds4-context.json"),
+      projectPath: this.loadedConfig?.projectPath ?? "",
+      loadedFiles: this.loadedConfig?.loadedFiles ?? [],
+      warnings: this.loadedConfig?.warnings ?? [],
+    };
+  }
+
+  setConfigValue(
+    path: string,
+    rawValue: string,
+    target: ConfigTarget,
+    options: { projectTrusted: boolean; cwd: string },
+  ): ConfigMutationResult {
+    const doc = findConfigField(path);
+    if (!doc) {
+      throw new Error(`Unknown configuration key: ${path}. See /context config for the full list.`);
+    }
+    const filePath = this.resolveConfigTarget(target, options);
+    const content = this.readConfigFile(filePath);
+    const value = applyConfigValue(content, path, rawValue, doc);
+    const { warnings } = validateConfigFile(content);
+    this.writeConfigFile(filePath, content);
+    return {
+      file: filePath,
+      global: target === "global",
+      value: describeConfigValue(value),
+      warnings,
+    };
+  }
+
+  unsetConfigValue(
+    path: string,
+    target: ConfigTarget,
+    options: { projectTrusted: boolean; cwd: string },
+  ): ConfigMutationResult {
+    const doc = findConfigField(path);
+    if (!doc) {
+      throw new Error(`Unknown configuration key: ${path}. See /context config for the full list.`);
+    }
+    const filePath = this.resolveConfigTarget(target, options);
+    const content = this.readConfigFile(filePath);
+    if (!removeConfigValue(content, path)) {
+      throw new Error(`${path} is not set in ${filePath}`);
+    }
+    const { warnings } = validateConfigFile(content);
+    this.writeConfigFile(filePath, content);
+    return { file: filePath, global: target === "global", warnings };
+  }
+
   shutdown(ctx?: ExtensionContext): void {
     if (ctx) this.syncSessionIndex(ctx);
     this.flushContextQuality();
@@ -2972,6 +3060,37 @@ export class Ds4ContextRuntime {
     this.logger.debug("runtime.closed", { sessionId: this.session?.sessionId });
   }
 
+  private resolveConfigTarget(target: ConfigTarget, options: { projectTrusted: boolean; cwd: string }): string {
+    if (target === "global") {
+      return this.loadedConfig?.globalPath
+        ?? join(this.dependencies.agentDir, "ds4-context.json");
+    }
+    if (!options.projectTrusted) {
+      throw new Error("Project configuration requires a trusted project; use /context config set/unset --global instead");
+    }
+    return this.loadedConfig?.projectPath
+      ?? join(options.cwd, this.dependencies.configDirName ?? ".pi", "ds4-context.json");
+  }
+
+  private readConfigFile(path: string): Record<string, unknown> {
+    if (!existsSync(path)) return {};
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      throw new Error(`Configuration file is malformed JSON: ${path}`);
+    }
+    if (!isConfigRecord(parsed)) {
+      throw new Error(`Configuration file must contain a JSON object: ${path}`);
+    }
+    return parsed;
+  }
+
+  private writeConfigFile(path: string, content: Record<string, unknown>): void {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`, "utf8");
+  }
+
   private getCompactionDiagnostics(ctx: ExtensionContext): CompactionDiagnostics {
     return this.compaction?.diagnostics(ctx) ?? defaultCompactionDiagnostics(this.config);
   }

package/src/pi-adapter/version.ts

@@ -1,4 +1,4 @@
-export const EXTENSION_VERSION = "0.3.1";
+export const EXTENSION_VERSION = "0.3.2";
 export const SUPPORTED_PI_VERSION = "0.84.3";
 export const OBSERVER_PLANNER_VERSION = "observer-model-aware-v1";
 export const PLANNER_VERSION = "managed-learned-ranking-v1";