elanous 0.2.22 → 0.2.24

package/src/intelligence-map/model-catalog.ts

@@ -620,6 +620,78 @@ export const BUILTIN_CATALOG: ModelCatalog = {
       notes: 'Apache 2.0 · 397B MoE · Q4 ~220GB · M3 Ultra 512GB only',
     },
 
+    // ── DeepSeek V4 · OpenRouter `openrouter/deepseek/<id>` 전용 (OR-DEEPSEEK-TUNE · 2026-10-11)
+    // id 는 OpenRouter slug(`deepseek/` 뒤) 그대로 — llm.ts openRouterReasoningField 가 이 id 로 openWeight 를
+    // 찾는다. 기본 effort 는 YAML 손 레코드(catalog/models/openrouter/ · #26055)의 `reasoning` 이 정본이고,
+    // 레코드가 없을 때만 이 openWeight 폴백(medium)을 탄다. 단가 = deepseek 공급자 엔드포인트 평시가
+    // (v4.1-flash·v4-pro-0813 은 #26055 와 같은 값) · 나머지는 /api/v1/models 목록가(2026-10-11 실측).
+    // effort 상한 xhigh(OpenRouter 는 max 를 400 으로 거부 → src/llm/openrouter-deepseek.ts 가 max→xhigh).
+    // provider 'other' — 직결 deepseek 공급자는 없다(새 공급자 이름을 만들지 않는다).
+    {
+      id: 'deepseek-v4-flash',
+      provider: 'other',
+      family: 'deepseek',
+      contextWindow: 1_048_576,
+      inputPerMtok: 0.03,
+      outputPerMtok: 1.28,
+      local: false,
+      openWeight: true,
+      localPullable: false,
+      tags: ['coding', 'moe', 'cheap', 'open-weight', 'long-context'],
+      bestFor: ['cheap-agentic', 'open-weight-bench'],
+      reasoningEffortCeiling: 'xhigh',
+      releasedAt: '2026-04-24',
+      notes: 'OpenRouter deepseek/deepseek-v4-flash · 1M ctx',
+    },
+    {
+      id: 'deepseek-v4.1-flash',
+      provider: 'other',
+      family: 'deepseek',
+      contextWindow: 1_048_576,
+      inputPerMtok: 0.15,
+      outputPerMtok: 0.60,
+      local: false,
+      openWeight: true,
+      localPullable: false,
+      tags: ['coding', 'moe', 'cheap', 'open-weight', 'long-context'],
+      bestFor: ['cheap-agentic', 'open-weight-bench'],
+      reasoningEffortCeiling: 'xhigh',
+      releasedAt: '2026-09-10',
+      notes: 'OpenRouter deepseek/deepseek-v4.1-flash · 1M ctx',
+    },
+    {
+      id: 'deepseek-v4-pro',
+      provider: 'other',
+      family: 'deepseek',
+      contextWindow: 1_048_576,
+      inputPerMtok: 0.2088,
+      outputPerMtok: 0.4176,
+      local: false,
+      openWeight: true,
+      localPullable: false,
+      tags: ['coding', 'moe', 'open-weight', 'flagship', 'long-context'],
+      bestFor: ['open-frontier', 'open-weight-bench'],
+      reasoningEffortCeiling: 'xhigh',
+      releasedAt: '2026-04-24',
+      notes: 'OpenRouter deepseek/deepseek-v4-pro · 0423 Preview 별칭 — 고정판은 deepseek-v4-pro-0813',
+    },
+    {
+      id: 'deepseek-v4-pro-0813',
+      provider: 'other',
+      family: 'deepseek',
+      contextWindow: 1_048_576,
+      inputPerMtok: 0.66,
+      outputPerMtok: 1.98,
+      local: false,
+      openWeight: true,
+      localPullable: false,
+      tags: ['coding', 'moe', 'open-weight', 'flagship', 'long-context'],
+      bestFor: ['open-frontier', 'open-weight-bench'],
+      reasoningEffortCeiling: 'xhigh',
+      releasedAt: '2026-08-13',
+      notes: 'OpenRouter deepseek/deepseek-v4-pro-0813 · 날짜 고정판',
+    },
+
     // ── GLM 5.x (Zhipu) · `api.z.ai` / `open.bigmodel.cn` · OpenAI-compat
     // GLM-5.1 (2026-04-07) is the current flagship — 754B MoE / 40B
     // active under MIT. All recent GLM models (4.6+) are open-weight,
@@ -794,6 +866,47 @@ export const BUILTIN_CATALOG: ModelCatalog = {
       mlxRepo: 'lmstudio-community/NVIDIA-Nemotron-3-Nano-30B-A3B-MLX-8bit',
       notes: 'NVIDIA Open Model License · 30B/3B MoE · 1M ctx · text+vision+audio+video · Q4 ~28GB / MLX-8bit ~36GB · M5 Max OK',
     },
+    // ⭐ 2026-10-10 (MK · MODEL-ROUTING-MATRIX) — `--child-llm-model` 이 이 둘을 «알 수 없음»으로 거부했다
+    //    (UX 17:36 실측 · 해석은 이 표 ⊕ src/anthropic/models.ts 만 본다). 값은 Anthropic 공식 1차
+    //    (platform.claude.com/내부 문서 `overview` · 2026-10-10T08:38Z 직접 확인)
+    //    ⊕ OpenRouter /api/v1/models 실측(05:10Z) 이 같다. 별칭(`sonnet`·`haiku`)은 옮기지 않는다 — 별개 결정.
+    // ⛔ 표의 «맨 끝»에 둔 것은 의도다 — `recommendModel` 은 같은 가격이면 표 순서로 고른다(안정 정렬).
+    //    haiku-5-5($0.10/$0.50)는 gpt-6-luna 와 값이 같아, 앞에 두면 'cheap' 추천이 조용히 haiku 로 바뀐다
+    //    (게다가 haiku 는 >100k 프롬프트가 5배라 이 칸 하나로는 싸다고 말할 수 없다). 추천 변경은 별개 결정.
+    {
+      // 📏 공식: Released 2026-09-28 · 1M ctx · 출력 128K · $2/$10 · 캐시 읽기 $0.10(입력의 5%) · Adaptive · 기본 effort high.
+      id: 'claude-sonnet-5-5',
+      provider: 'anthropic',
+      family: 'claude',
+      contextWindow: 1_000_000,
+      inputPerMtok: 2,
+      outputPerMtok: 10,
+      local: false,
+      tags: ['reasoning', 'coding', 'balanced', 'long-context'],
+      bestFor: ['daily-coding', 'multi-turn-chat', 'summarization'],
+      envKey: 'ANTHROPIC_API_KEY',
+      reservedOutputTokens: 8_000,
+      reasoningEffortCeiling: 'high',  // adaptive thinking (공식 «Adaptive»)
+      releasedAt: '2026-09-28',
+    },
+    {
+      // 📏 공식: Released 2026-10-07 · 1M ctx · 출력 128K · Adaptive · 기본 effort medium.
+      // ⚠️ 가격이 프롬프트 길이 구간으로 갈린다 — ≤100k 토큰 $0.10/$0.50 · >100k $0.50/$2.50(요청 전체).
+      //    칸이 하나라 «≤100k» 를 싣는다.
+      id: 'claude-haiku-5-5',
+      provider: 'anthropic',
+      family: 'claude',
+      contextWindow: 1_000_000,
+      inputPerMtok: 0.1,
+      outputPerMtok: 0.5,
+      local: false,
+      tags: ['classification', 'summarization', 'cheap', 'fast', 'long-context'],
+      bestFor: ['classification', 'routing', 'bulk-summarization', 'subagent-tasks'],
+      envKey: 'ANTHROPIC_API_KEY',
+      reservedOutputTokens: 8_000,
+      reasoningEffortCeiling: 'high',  // 공식: adaptive thinking ⊕ effort 파라미터 지원(haiku-4-5 의 'low' 와 다르다)
+      releasedAt: '2026-10-07',
+    },
   ],
 };
 

package/src/knowledge/kgs/pack.ts

@@ -50,14 +50,17 @@ export interface PackId {
 }
 
 const SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/;
-const VERSION_RE = /^\d+\.\d+\.\d+(?:-[a-z0-9-]+)?$/;
+const VERSION_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[a-z0-9-]+(?:\.[a-z0-9-]+)*)?$/;
 
 export function isPackSlug(v: unknown): v is string {
   return typeof v === 'string' && SLUG_RE.test(v);
 }
 
 export function isPackVersion(v: unknown): v is string {
-  return typeof v === 'string' && VERSION_RE.test(v);
+  if (typeof v !== 'string' || !VERSION_RE.test(v)) return false;
+  const separator = v.indexOf('-');
+  const prerelease = separator < 0 ? undefined : v.slice(separator + 1);
+  return prerelease === undefined || prerelease.split('.').every(id => !/^\d+$/.test(id) || id === '0' || !id.startsWith('0'));
 }
 
 export function packIdString(id: PackId): string {

package/src/knowledge/kgs/sqlite-store.ts

@@ -209,6 +209,21 @@ export class KgsSqliteStore {
     );
   }
 
+  /** Remove only the selected version; standalone pack cards live inside its payload. */
+  deletePack(slug: string, version: string): boolean {
+    return this.db.run('DELETE FROM kgs_pack WHERE slug = ? AND version = ?', [slug, version]).changes > 0;
+  }
+
+  /** Switch versions as one SQLite transaction so failed upgrades retain the old index. */
+  replacePack(previous: { slug: string; version: string }, next: Pack): void {
+    this.db.transaction(() => {
+      if (!this.readPack(previous.slug, previous.version)) throw new Error('pack not installed');
+      if (this.readPack(next.metadata.id.slug, next.metadata.id.version)) throw new Error('pack version already installed');
+      this.writePack(next);
+      if (!this.deletePack(previous.slug, previous.version)) throw new Error('pack not removed');
+    })();
+  }
+
   readPack(slug: string, version: string): Pack | null {
     const row = this.db
       .query(`SELECT payload FROM kgs_pack WHERE slug = ? AND version = ?`)

package/src/knowledge/tools/knowledge-query.ts

@@ -2,10 +2,12 @@
 
 import type { LLMToolSpec } from '../../llm.js';
 import { discoverObsidianVault, type ObsidianVault } from '../../auto-research/obsidian-bridge.js';
-import { knowledgeQuery } from '../query.js';
+import { knowledgeQuery, queryInstalledPack } from '../query.js';
 import type { KnowledgeQueryInput, KnowledgeQueryResult } from '../types.js';
 
 export interface KnowledgeQueryToolInput {
+  pack_id?: string;
+  question?: string;
   tags?: string[];
   fulltext?: string;
   kind?: 'all' | 'rca' | 'a3' | 'incident' | 'wiki' | 'repomap' | 'note';
@@ -16,6 +18,8 @@ export interface KnowledgeQueryToolInput {
 
 export interface KnowledgeQueryToolResult {
   output: string;
+  /** Cited cards when pack_id is supplied; absent on the existing vault query path. */
+  pack_hits?: ReturnType<typeof queryInstalledPack>;
   results: KnowledgeQueryResult['results'];
   total: number;
   truncated: boolean;
@@ -24,12 +28,24 @@ export interface KnowledgeQueryToolResult {
 
 export interface KnowledgeQueryDispatchOpts {
   vault?: ObsidianVault;
+  searchPack?: typeof queryInstalledPack;
 }
 
 export async function dispatchKnowledgeQuery(
   input: KnowledgeQueryToolInput,
   opts: KnowledgeQueryDispatchOpts = {},
 ): Promise<KnowledgeQueryToolResult> {
+  if (input.pack_id !== undefined) {
+    try {
+      if (!input.question?.trim()) throw new Error('question required for pack search');
+      const hits = (opts.searchPack ?? queryInstalledPack)(input.pack_id, input.question);
+      return { output: hits.map(hit => `[${hit.ref}] ${hit.title}: ${hit.body}`).join('\n') || 'No matching installed pack cards.',
+        pack_hits: hits, results: [], total: hits.length, truncated: false };
+    } catch (error) {
+      return { output: `KnowledgeQuery failed: ${error instanceof Error ? error.message : String(error)}`,
+        pack_hits: [], results: [], total: 0, truncated: false };
+    }
+  }
   const vault = opts.vault ?? discoverObsidianVault();
   const notices: string[] = [];
   if (vault.isSimulated) {
@@ -75,13 +91,15 @@ export function buildKnowledgeQueryTool(): LLMToolSpec {
   return {
     name: 'KnowledgeQuery',
     description:
-      'Search the Obsidian knowledge vault (or simulated fallback) for notes matching tags, fulltext regex, '
+      'Search an explicitly installed knowledge pack by pack_id and question for cited cards, or search the Obsidian knowledge vault (or simulated fallback) for notes matching tags, fulltext regex, '
       + 'or kind. Returns paths + parsed frontmatter + excerpts (and optionally full body). Use this to look '
       + 'up prior incident analyses, tool docs, repo maps, or any markdown you or another agent wrote earlier. '
       + 'For writing, use KnowledgeWrite.',
     parameters: {
       type: 'object',
       properties: {
+        pack_id: { type: 'string', description: 'Installed pack id, e.g. pack:semiconductor-process-public@0.1.0. Requires question.' },
+        question: { type: 'string', description: 'Search words when pack_id is provided.' },
         tags: {
           type: 'array',
           items: { type: 'string' },

package/src/knowledge/write.ts

@@ -7,14 +7,21 @@
 //   - automatic tag / kind merge into frontmatter
 //   - Poka-Yoke validation → atomic-write ONLY on pass
 
-import { existsSync, statSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { packDirDeterministic } from '../market/tgz.js';
+import { verifyIndex } from '../market/signed-index.js';
 import {
   writeNote,
   type ObsidianVault,
 } from '../auto-research/obsidian-bridge.js';
 import type { PokaSchema, ValidationFailure } from '../cft/pokayoke.js';
 import { validate } from '../cft/pokayoke.js';
+import { isPackSlug, isPackVersion, packIdString, type Pack, type PackId } from './kgs/pack.js';
+import { isKnowledgeKind, type KnowledgeCard } from './kgs/types.js';
+import { kgsStoreSingleton, type KgsSqliteStore } from './kgs/sqlite-store.js';
 import type {
   KnowledgeKind,
   KnowledgeWriteInput,
@@ -141,6 +148,231 @@ export function knowledgeWrite(
   return { ok: true, path: abs, relPath: rel };
 }
 
+/** KPACK1 directory manifest. Market signatures belong to the index, not this file. */
+export interface KnowledgePackManifest {
+  kind: 'knowledge-pack';
+  name: string;
+  version: string;
+  description: string;
+  signature: { alg: 'ed25519'; keyId: string };
+  dependencies: readonly { market: string; name: string; version: string }[];
+  license: string;
+  visibility: 'public' | 'internal';
+  content: readonly { type: 'document' | 'glossary' | 'procedure' | 'rule' | 'qa'; path: string }[];
+}
+
+/** Verified marketplace evidence is required when installing from a market. The URL→key binding is caller-owned. */
+export interface KnowledgePackMarketProof {
+  marketplaceBytes: Uint8Array;
+  signatureText: string;
+  trustedKeys: ReadonlyArray<{ keyId: string; publicKey: string }>;
+  artifactBytes: Uint8Array;
+  lastSequence?: number;
+}
+
+export type KnowledgePackStore = Pick<KgsSqliteStore, 'readPack' | 'writePack' | 'deletePack' | 'replacePack'>;
+
+function object(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requiredString(value: unknown, field: string): asserts value is string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`KPACK1: ${field} must be a non-empty string`);
+}
+
+/** Never follow a symlink, including any ancestor of an enumerated content file. */
+function safePackFile(root: string, path: string): string {
+  if (!path || isAbsolute(path) || path.includes('\\') || path.split('/').some(part => !part || part === '.' || part === '..')) {
+    throw new Error(`KPACK1: unsafe path: ${path}`);
+  }
+  let current = root;
+  for (const part of path.split('/')) {
+    current = join(current, part);
+    const stat = lstatSync(current);
+    if (stat.isSymbolicLink()) throw new Error(`KPACK1: symbolic link: ${path}`);
+  }
+  if (!lstatSync(current).isFile()) throw new Error(`KPACK1: not a file: ${path}`);
+  return current;
+}
+
+/** Validate the manifest and all listed content before any store mutation. */
+export function validateKnowledgePack(directory: string): { manifest: KnowledgePackManifest; pack: Pack } {
+  if (!lstatSync(directory).isDirectory() || lstatSync(directory).isSymbolicLink()) throw new Error('KPACK1: not a directory');
+  // The packer traverses the whole directory and refuses even unlisted symlinks/special files.
+  packDirDeterministic(directory);
+  return validatePackFiles(path => readFileSync(safePackFile(directory, path), 'utf8'));
+}
+
+/** Read the regular files of a deterministic ustar gzip archive (as produced by packDirDeterministic). */
+const MAX_ARCHIVE_BYTES = 32 * 1024 * 1024;
+
+function archiveFiles(archive: Uint8Array): Map<string, string> {
+  if (archive.byteLength > MAX_ARCHIVE_BYTES) throw new Error('KPACK1: archive too large');
+  let tar: Buffer;
+  // Bound the inflated size so a small compressed bomb cannot exhaust memory.
+  try { tar = gunzipSync(archive, { maxOutputLength: MAX_ARCHIVE_BYTES }); }
+  catch (error) { throw new Error(`KPACK1: archive unreadable or larger than ${MAX_ARCHIVE_BYTES} bytes: ${String(error)}`); }
+  const files = new Map<string, string>();
+  const field = (header: Buffer, offset: number, width: number) => {
+    const raw = header.subarray(offset, offset + width);
+    const end = raw.indexOf(0);
+    return raw.subarray(0, end < 0 ? width : end).toString('utf8');
+  };
+  for (let offset = 0; offset + 512 <= tar.length;) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every(byte => byte === 0)) break;
+    const type = field(header, 156, 1);
+    if (type !== '0' && type !== '') throw new Error('KPACK1: archive contains a non-regular entry');
+    const size = Number.parseInt(field(header, 124, 12).trim(), 8);
+    if (!Number.isSafeInteger(size) || size < 0 || offset + 512 + size > tar.length) throw new Error('KPACK1: malformed archive');
+    const name = field(header, 0, 100);
+    const prefix = field(header, 345, 155);
+    const path = prefix ? `${prefix}/${name}` : name;
+    if (files.has(path)) throw new Error(`KPACK1: duplicate archive entry: ${path}`);
+    files.set(path, tar.subarray(offset + 512, offset + 512 + size).toString('utf8'));
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
+/** Validate from verified archive bytes, so what is stored is exactly what the signature covered. */
+export function validateKnowledgePackArchive(archive: Uint8Array): { manifest: KnowledgePackManifest; pack: Pack } {
+  const files = archiveFiles(archive);
+  return validatePackFiles((path) => {
+    const content = files.get(path);
+    if (content === undefined) throw new Error(`KPACK1: missing from archive: ${path}`);
+    return content;
+  });
+}
+
+function validatePackFiles(read: (path: string) => string): { manifest: KnowledgePackManifest; pack: Pack } {
+  const value: unknown = JSON.parse(read('knowledge-pack.json'));
+  if (!object(value) || value.kind !== 'knowledge-pack') throw new Error('KPACK1: invalid kind');
+  if (!isPackSlug(value.name) || !isPackVersion(value.version)) throw new Error('KPACK1: invalid name or version');
+  requiredString(value.description, 'description');
+  requiredString(value.license, 'license');
+  if (!object(value.signature) || value.signature.alg !== 'ed25519' || typeof value.signature.keyId !== 'string' || !/^[a-fA-F0-9]{8}$/.test(value.signature.keyId)) throw new Error('KPACK1: invalid signature declaration');
+  if (value.visibility !== 'public' && value.visibility !== 'internal') throw new Error('KPACK1: invalid visibility');
+  if (!Array.isArray(value.dependencies) || !Array.isArray(value.content) || value.content.length === 0 || value.content.length > 200) throw new Error('KPACK1: invalid dependencies or content');
+  for (const dep of value.dependencies) {
+    if (!object(dep) || typeof dep.market !== 'string' || !/^https:\/\//.test(dep.market) || !isPackSlug(dep.name) || typeof dep.version !== 'string' || !dep.version.trim()) throw new Error('KPACK1: invalid dependency');
+  }
+  // No dependency resolver is available in standalone storage; never silently install an incomplete pack.
+  if (value.dependencies.length) throw new Error('KPACK1: dependencies require a verified resolver');
+  const seen = new Set<string>();
+  const cards: KnowledgeCard[] = [];
+  for (const entry of value.content) {
+    if (!object(entry) || !['document', 'glossary', 'procedure', 'rule', 'qa'].includes(entry.type as string) || typeof entry.path !== 'string' || !entry.path.startsWith('content/') || !entry.path.endsWith('.json')) throw new Error('KPACK1: invalid content entry');
+    if (seen.has(entry.path)) throw new Error(`KPACK1: duplicate content: ${entry.path}`);
+    seen.add(entry.path);
+    const item: unknown = JSON.parse(read(entry.path));
+    if (!object(item) || item.type !== entry.type) throw new Error(`KPACK1: invalid content: ${entry.path}`);
+    requiredString(item.title, `${entry.path}.title`);
+    requiredString(item.source, `${entry.path}.source`);
+    if (item.kind !== undefined && !isKnowledgeKind(item.kind)) throw new Error(`KPACK1: invalid content kind: ${entry.path}`);
+    const fields: Record<string, readonly string[]> = {
+      document: ['body'], glossary: ['term', 'definition'], procedure: ['preconditions'],
+      rule: ['scope', 'basis'], qa: ['question', 'answer'],
+    };
+    for (const field of fields[entry.type as string]!) requiredString(item[field], `${entry.path}.${field}`);
+    if (entry.type === 'procedure' && (!Array.isArray(item.steps) || !item.steps.length || !item.steps.every((step: unknown) => typeof step === 'string' && step.trim()))) throw new Error(`KPACK1: ${entry.path}.steps must be non-empty strings`);
+    const body = entry.type === 'document' ? item.body as string : entry.type === 'procedure'
+      ? `${item.preconditions}\n${(item.steps as string[]).join('\n')}`
+      : fields[entry.type as string]!.map(field => item[field]).join('\n');
+    const id = `card:${createHash('sha256').update(entry.path).digest('hex').slice(0, 16)}`;
+    const timestamp = '1970-01-01T00:00:00.000Z';
+    cards.push({ schema_version: 2, id, title: item.title, body, kind: isKnowledgeKind(item.kind) ? item.kind : 'card',
+      nature: 'fact', reliability: 'self-reported', author: value.name,
+      createdAt: timestamp, updatedAt: timestamp, source: { kind: 'external', url: item.source }, tags: [] });
+  }
+  const manifest = value as unknown as KnowledgePackManifest;
+  return { manifest, pack: {
+    schema_version: 2,
+    metadata: { id: { slug: manifest.name, version: manifest.version }, title: manifest.name,
+      intent: manifest.description, audience: manifest.visibility === 'public' ? 'public' : 'team',
+      kind: 'generic', createdAt: '1970-01-01T00:00:00.000Z', updatedAt: '1970-01-01T00:00:00.000Z',
+      author: manifest.name, tags: [] }, cards,
+  } };
+}
+
+/**
+ * Market path: verify the signed index and artifact first, then build the pack
+ * from those verified bytes (never from a second read of the directory).
+ */
+function verifiedMarketPack(directory: string, proof: KnowledgePackMarketProof): { manifest: KnowledgePackManifest; pack: Pack } {
+  const verified = verifyIndex(proof);
+  if (!verified.ok) throw new Error(`KPACK1: index ${verified.reason}: ${verified.detail}`);
+  const artifact = Buffer.from(proof.artifactBytes);
+  const sha256 = createHash('sha256').update(artifact).digest('hex');
+  const listed = verified.index.knowledgePacks?.filter(pack => pack.artifact.bytes === artifact.byteLength && pack.artifact.sha256.toLowerCase() === sha256) ?? [];
+  if (!listed.length) throw new Error('KPACK1: artifact hash or size mismatch');
+  const result = validateKnowledgePackArchive(artifact);
+  const { manifest } = result;
+  if (verified.keyId !== manifest.signature.keyId) throw new Error('KPACK1: manifest keyId differs from signed index');
+  const entry = listed.find(pack => pack.name === manifest.name && pack.version === manifest.version);
+  if (!entry || entry.visibility !== manifest.visibility || (entry.visibility === 'internal' && !entry.enterpriseId)) throw new Error('KPACK1: pack absent from signed index');
+  // The local directory must still be the extraction of this artifact.
+  validateKnowledgePack(directory);
+  if (Buffer.compare(Buffer.from(packDirDeterministic(directory)), artifact) !== 0) throw new Error('KPACK1: extracted directory differs from verified artifact');
+  return result;
+}
+
+/** Local-path installs validate content; market installs additionally require signed-index and archive proof. */
+export function installKnowledgePack(directory: string, store: KnowledgePackStore = kgsStoreSingleton(), proof?: KnowledgePackMarketProof): string {
+  const { manifest, pack } = proof ? verifiedMarketPack(directory, proof) : validateKnowledgePack(directory);
+  if (store.readPack(manifest.name, manifest.version)) throw new Error(`KPACK1: already installed: ${packIdString(pack.metadata.id)}`);
+  store.writePack(pack);
+  return packIdString(pack.metadata.id);
+}
+
+export function removeKnowledgePack(id: PackId, store: KnowledgePackStore = kgsStoreSingleton()): boolean {
+  if (!isPackSlug(id.slug) || !isPackVersion(id.version)) throw new Error('KPACK1: invalid pack id');
+  return store.deletePack(id.slug, id.version);
+}
+
+function comparePackVersions(next: string, previous: string): number {
+  if (!isPackVersion(next) || !isPackVersion(previous)) throw new Error('KPACK1: invalid pack version');
+  const nextSeparator = next.indexOf('-');
+  const previousSeparator = previous.indexOf('-');
+  const nextCore = nextSeparator < 0 ? next : next.slice(0, nextSeparator);
+  const previousCore = previousSeparator < 0 ? previous : previous.slice(0, previousSeparator);
+  const nextPre = nextSeparator < 0 ? undefined : next.slice(nextSeparator + 1);
+  const previousPre = previousSeparator < 0 ? undefined : previous.slice(previousSeparator + 1);
+  const left = nextCore.split('.').map(BigInt);
+  const right = previousCore.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (left[i] !== right[i]) return left[i]! > right[i]! ? 1 : -1;
+  }
+  if (nextPre === previousPre) return 0;
+  if (!nextPre) return 1;
+  if (!previousPre) return -1;
+  const nextIdentifiers = nextPre.split('.');
+  const previousIdentifiers = previousPre.split('.');
+  for (let i = 0; i < Math.min(nextIdentifiers.length, previousIdentifiers.length); i++) {
+    const nextIdentifier = nextIdentifiers[i]!;
+    const previousIdentifier = previousIdentifiers[i]!;
+    if (nextIdentifier === previousIdentifier) continue;
+    const nextNumeric = /^\d+$/.test(nextIdentifier);
+    const previousNumeric = /^\d+$/.test(previousIdentifier);
+    if (nextNumeric && previousNumeric) {
+      return BigInt(nextIdentifier) > BigInt(previousIdentifier) ? 1 : -1;
+    }
+    if (nextNumeric) return -1;
+    if (previousNumeric) return 1;
+    return nextIdentifier > previousIdentifier ? 1 : -1;
+  }
+  return Math.sign(nextIdentifiers.length - previousIdentifiers.length);
+}
+
+/** Atomically switch one installed version after the replacement has passed validation. */
+export function upgradeKnowledgePack(previous: PackId, directory: string, store: KnowledgePackStore = kgsStoreSingleton(), proof?: KnowledgePackMarketProof): string {
+  if (!isPackSlug(previous.slug) || !isPackVersion(previous.version)) throw new Error('KPACK1: invalid previous pack id');
+  const { manifest, pack } = proof ? verifiedMarketPack(directory, proof) : validateKnowledgePack(directory);
+  if (manifest.name !== previous.slug || comparePackVersions(manifest.version, previous.version) <= 0) throw new Error('KPACK1: upgrade requires a newer version of the same pack');
+  store.replacePack(previous, pack);
+  return packIdString(pack.metadata.id);
+}
+
 /** Test helper — size of the KIND_SCHEMAS dict for assertion. */
 export function _kindSchemaCountForTest(): number {
   return Object.keys(KIND_SCHEMAS).length;