@pellux/goodvibes-tui 0.18.4

package/src/knowledge/consolidation.ts

@@ -0,0 +1,346 @@
+import type { MemoryClass, MemoryRegistry, MemoryScope } from '../state/index.ts';
+import type { KnowledgeStore } from '@pellux/goodvibes-sdk/platform/knowledge/store';
+import type {
+  KnowledgeConsolidationCandidateRecord,
+  KnowledgeConsolidationReportRecord,
+  KnowledgeNodeRecord,
+  KnowledgeSourceRecord,
+  KnowledgeUsageRecord,
+} from '@pellux/goodvibes-sdk/platform/knowledge/types';
+import {
+  DEEP_CONSOLIDATION_AUTOPROMOTE_THRESHOLD,
+  LIGHT_CONSOLIDATION_THRESHOLD,
+  coerceStringArray,
+  mergeTags,
+  slugify,
+  summarizeCompact,
+  topKeywords,
+  usageWindowCutoff,
+} from './internal.ts';
+
+export interface KnowledgeConsolidationContext {
+  readonly store: KnowledgeStore;
+  readonly memoryRegistry: Pick<MemoryRegistry, 'add' | 'getStore'>;
+  readonly syncReviewedMemory: () => Promise<void>;
+}
+
+export async function decideKnowledgeConsolidationCandidate(
+  context: KnowledgeConsolidationContext,
+  id: string,
+  decision: 'accept' | 'reject' | 'supersede',
+  input: {
+    readonly decidedBy?: string;
+    readonly memoryClass?: string;
+    readonly scope?: string;
+    readonly detail?: string;
+  } = {},
+): Promise<KnowledgeConsolidationCandidateRecord> {
+  await context.store.init();
+  const candidate = context.store.getConsolidationCandidate(id);
+  if (!candidate) throw new Error(`Unknown knowledge consolidation candidate: ${id}`);
+  const decidedAt = Date.now();
+  let acceptedMemoryId: string | undefined;
+  if (decision === 'accept' && candidate.candidateType === 'memory-promotion') {
+    const record = context.store.getItem(candidate.subjectId);
+    await context.memoryRegistry.getStore().init();
+    const summary = summarizeCompact(candidate.title, 160) ?? candidate.title;
+    const detail = input.detail
+      ?? candidate.summary
+      ?? record?.source?.summary
+      ?? record?.node?.summary
+      ?? summary;
+    const tags = mergeTags(
+      candidate.evidence,
+      record?.source?.tags,
+      record?.node?.aliases,
+      coerceStringArray(candidate.metadata.tags),
+    );
+    const memory = await context.memoryRegistry.add({
+      cls: (input.memoryClass ?? candidate.suggestedMemoryClass ?? 'fact') as MemoryClass,
+      scope: (input.scope ?? candidate.suggestedScope ?? 'project') as MemoryScope,
+      summary,
+      detail,
+      tags,
+      provenance: [
+        ...(record?.source?.sessionId ? [{ kind: 'session' as const, ref: record.source.sessionId }] : []),
+        { kind: 'event', ref: candidate.id, label: 'knowledge consolidation candidate' },
+      ],
+      review: {
+        state: 'reviewed',
+        confidence: Math.max(60, Math.min(100, Math.round(candidate.score))),
+        reviewedAt: decidedAt,
+        reviewedBy: input.decidedBy,
+      },
+    });
+    acceptedMemoryId = memory.id;
+    await context.syncReviewedMemory();
+  }
+  return context.store.upsertConsolidationCandidate({
+    id: candidate.id,
+    candidateType: candidate.candidateType,
+    subjectKind: candidate.subjectKind,
+    subjectId: candidate.subjectId,
+    title: candidate.title,
+    summary: candidate.summary,
+    score: candidate.score,
+    evidence: candidate.evidence,
+    suggestedMemoryClass: input.memoryClass ?? candidate.suggestedMemoryClass,
+    suggestedScope: input.scope ?? candidate.suggestedScope,
+    status: decision === 'accept' ? 'accepted' : decision === 'reject' ? 'rejected' : 'superseded',
+    decidedAt,
+    decidedBy: input.decidedBy,
+    metadata: {
+      ...candidate.metadata,
+      ...(acceptedMemoryId ? { acceptedMemoryId } : {}),
+    },
+  });
+}
+
+export async function refreshKnowledgeConsolidationCandidates(
+  context: KnowledgeConsolidationContext,
+  limit = 24,
+): Promise<KnowledgeConsolidationCandidateRecord[]> {
+  await context.store.init();
+  await context.syncReviewedMemory();
+  const usageStats = await buildUsageStats(context);
+  const proposals: KnowledgeConsolidationCandidateRecord[] = [];
+  const seenSubjects = new Set<string>();
+
+  for (const [key, stats] of usageStats.entries()) {
+    const [subjectKind, subjectId] = key.split(':', 2) as [KnowledgeConsolidationCandidateRecord['subjectKind'], string];
+    if (subjectKind === 'issue') continue;
+    const item = context.store.getItem(subjectId);
+    if (!item?.source && !item?.node) continue;
+    const subjectTitle = item.source?.title ?? item.source?.canonicalUri ?? item.node?.title ?? subjectId;
+    const subjectSummary = summarizeCompact(item.source?.summary ?? item.node?.summary ?? item.source?.description);
+    const relationCount = subjectKind === 'source'
+      ? context.store.edgesFor('source', subjectId).length
+      : context.store.edgesFor('node', subjectId).length;
+    const score = Math.round(
+      scoreUsageBoost(stats)
+      + Math.min(16, relationCount * 2)
+      + (item.node?.kind === 'memory' ? 10 : 0),
+    );
+    if (score < LIGHT_CONSOLIDATION_THRESHOLD) continue;
+    const candidateType: KnowledgeConsolidationCandidateRecord['candidateType'] =
+      item.node?.kind === 'memory' && item.node.status === 'stale'
+        ? 'memory-review'
+        : subjectKind === 'source' && isSourcePastRefreshWindow(item.source!)
+          ? 'source-refresh'
+          : 'memory-promotion';
+    const evidence = mergeTags(
+      [
+        `used ${stats.count} time(s) in the last 30 days`,
+        `observed via ${stats.usageKinds.size} usage pattern(s)`,
+        `linked to ${relationCount} graph relation(s)`,
+      ],
+      subjectKind === 'source' ? item.source?.tags : item.node?.aliases,
+    ).slice(0, 8);
+    const candidate = await context.store.upsertConsolidationCandidate({
+      candidateType,
+      subjectKind,
+      subjectId,
+      title: subjectTitle,
+      summary: subjectSummary,
+      score,
+      evidence,
+      suggestedMemoryClass: inferMemoryClassForCandidate(context, subjectKind, subjectId),
+      suggestedScope: 'project',
+      metadata: {
+        usageCount: stats.count,
+        lastUsedAt: stats.lastUsedAt,
+        usageKinds: [...stats.usageKinds],
+        relationCount,
+      },
+    });
+    proposals.push(candidate);
+    seenSubjects.add(`${candidate.candidateType}:${candidate.subjectKind}:${candidate.subjectId}`);
+  }
+
+  for (const existing of context.store.listConsolidationCandidates(1_000, { status: 'open' })) {
+    const key = `${existing.candidateType}:${existing.subjectKind}:${existing.subjectId}`;
+    if (seenSubjects.has(key)) continue;
+    await context.store.upsertConsolidationCandidate({
+      id: existing.id,
+      candidateType: existing.candidateType,
+      status: 'superseded',
+      subjectKind: existing.subjectKind,
+      subjectId: existing.subjectId,
+      title: existing.title,
+      summary: existing.summary,
+      score: existing.score,
+      evidence: existing.evidence,
+      suggestedMemoryClass: existing.suggestedMemoryClass,
+      suggestedScope: existing.suggestedScope,
+      metadata: existing.metadata,
+    });
+  }
+
+  return proposals
+    .sort((a, b) => b.score - a.score || b.updatedAt - a.updatedAt || a.id.localeCompare(b.id))
+    .slice(0, Math.max(1, limit));
+}
+
+export async function runKnowledgeConsolidation(
+  context: KnowledgeConsolidationContext,
+  kind: Extract<KnowledgeConsolidationReportRecord['kind'], 'light-consolidation' | 'deep-consolidation'>,
+  input: { readonly limit?: number; readonly autoPromote: boolean },
+): Promise<KnowledgeConsolidationReportRecord> {
+  const limit = Math.max(1, input.limit ?? 24);
+  const candidates = await refreshKnowledgeConsolidationCandidates(context, limit);
+  let accepted = 0;
+  let rejected = 0;
+  let superseded = 0;
+  if (input.autoPromote) {
+    for (const candidate of candidates) {
+      if (candidate.candidateType !== 'memory-promotion') continue;
+      if (candidate.score < DEEP_CONSOLIDATION_AUTOPROMOTE_THRESHOLD) continue;
+      const decided = await decideKnowledgeConsolidationCandidate(context, candidate.id, 'accept', {
+        decidedBy: 'knowledge.deep-consolidation',
+        memoryClass: candidate.suggestedMemoryClass,
+        scope: candidate.suggestedScope,
+      });
+      if (decided.status === 'accepted') accepted += 1;
+    }
+  }
+  const current = context.store.listConsolidationCandidates(1_000);
+  for (const candidate of current) {
+    if (candidate.status === 'rejected') rejected += 1;
+    if (candidate.status === 'superseded') superseded += 1;
+  }
+  const openCount = current.filter((entry) => entry.status === 'open').length;
+  return context.store.upsertConsolidationReport({
+    kind,
+    title: kind === 'light-consolidation' ? 'Light Consolidation Report' : 'Deep Consolidation Report',
+    summary: kind === 'light-consolidation'
+      ? `Reviewed ${candidates.length} high-signal knowledge subjects and refreshed the consolidation queue.`
+      : `Reviewed ${candidates.length} high-signal knowledge subjects and auto-promoted the highest-confidence candidates into durable memory.`,
+    highlights: candidates.slice(0, 6).map((candidate) => `${candidate.title} (${candidate.candidateType}, score ${candidate.score})`),
+    metrics: {
+      candidateCount: candidates.length,
+      openCount,
+      acceptedCount: accepted,
+      rejectedCount: rejected,
+      supersededCount: superseded,
+    },
+    metadata: {
+      autoPromote: input.autoPromote,
+    },
+  });
+}
+
+export async function syncReviewedKnowledgeMemory(context: { readonly syncReviewedMemory: () => Promise<void> }): Promise<void> {
+  await context.syncReviewedMemory();
+}
+
+async function buildUsageStats(context: KnowledgeConsolidationContext, limit = 10_000): Promise<Map<string, {
+  count: number;
+  scoreTotal: number;
+  lastUsedAt: number;
+  usageKinds: Set<string>;
+  sessionIds: Set<string>;
+}>> {
+  const stats = new Map<string, {
+    count: number;
+    scoreTotal: number;
+    lastUsedAt: number;
+    usageKinds: Set<string>;
+    sessionIds: Set<string>;
+  }>();
+  const cutoff = usageWindowCutoff();
+  for (const record of context.store.listUsageRecords(limit)) {
+    if (record.createdAt < cutoff) continue;
+    const key = `${record.targetKind}:${record.targetId}`;
+    const current = stats.get(key) ?? {
+      count: 0,
+      scoreTotal: 0,
+      lastUsedAt: 0,
+      usageKinds: new Set<string>(),
+      sessionIds: new Set<string>(),
+    };
+    current.count += 1;
+    current.scoreTotal += Number(record.score ?? 0);
+    current.lastUsedAt = Math.max(current.lastUsedAt, record.createdAt);
+    current.usageKinds.add(record.usageKind);
+    if (record.sessionId) current.sessionIds.add(record.sessionId);
+    stats.set(key, current);
+  }
+  return stats;
+}
+
+function scoreUsageBoost(stats: {
+  count: number;
+  scoreTotal: number;
+  lastUsedAt: number;
+  usageKinds: Set<string>;
+  sessionIds: Set<string>;
+} | undefined): number {
+  if (!stats) return 0;
+  const frequency = Math.min(28, stats.count * 4);
+  const diversity = Math.min(14, stats.usageKinds.size * 3 + stats.sessionIds.size * 2);
+  const averageScore = stats.count > 0 ? stats.scoreTotal / stats.count : 0;
+  const scoreBoost = Math.min(12, Math.max(0, averageScore / 12));
+  const ageMs = Math.max(0, Date.now() - stats.lastUsedAt);
+  const recency = ageMs <= (24 * 60 * 60 * 1000) ? 10 : ageMs <= 7 * (24 * 60 * 60 * 1000) ? 6 : ageMs <= 14 * (24 * 60 * 60 * 1000) ? 3 : 0;
+  return frequency + diversity + scoreBoost + recency;
+}
+
+function inferMemoryClassForCandidate(
+  context: KnowledgeConsolidationContext,
+  subjectKind: KnowledgeConsolidationCandidateRecord['subjectKind'],
+  subjectId: string,
+): MemoryClass {
+  if (subjectKind === 'node') {
+    const node = context.store.getNode(subjectId);
+    switch (node?.kind) {
+      case 'project':
+      case 'capability':
+      case 'repo':
+      case 'service':
+      case 'environment':
+        return 'architecture';
+      case 'provider':
+        return 'fact';
+      case 'user':
+        return 'ownership';
+      case 'memory':
+        return 'fact';
+      default:
+        return 'fact';
+    }
+  }
+  const source = context.store.getSource(subjectId);
+  switch (source?.sourceType) {
+    case 'repo':
+      return 'architecture';
+    case 'bookmark':
+    case 'url':
+    case 'bookmark-list':
+      return 'fact';
+    case 'document':
+      return 'runbook';
+    default:
+      return 'fact';
+  }
+}
+
+function isSourcePastRefreshWindow(source: KnowledgeSourceRecord): boolean {
+  if (!source.lastCrawledAt) return source.status === 'stale';
+  return source.lastCrawledAt < (Date.now() - getSourceRefreshWindowMs(source));
+}
+
+function getSourceRefreshWindowMs(source: KnowledgeSourceRecord): number {
+  const connectorKey = source.connectorId === 'url-list' ? 'url-list' : source.connectorId;
+  return {
+    bookmark: 7 * 24 * 60 * 60 * 1000,
+    'bookmark-list': 7 * 24 * 60 * 60 * 1000,
+    'url-list': 7 * 24 * 60 * 60 * 1000,
+    url: 14 * 24 * 60 * 60 * 1000,
+    repo: 14 * 24 * 60 * 60 * 1000,
+    document: 21 * 24 * 60 * 60 * 1000,
+    image: 21 * 24 * 60 * 60 * 1000,
+    dataset: 30 * 24 * 60 * 60 * 1000,
+    manual: 45 * 24 * 60 * 60 * 1000,
+    other: 30 * 24 * 60 * 60 * 1000,
+  }[connectorKey] ?? 30 * 24 * 60 * 60 * 1000;
+}

package/src/knowledge/graphql.ts

@@ -0,0 +1,324 @@
+import { GraphQLError, buildSchema, graphql, parse, printSchema } from 'graphql';
+import type { KnowledgeService } from './service.ts';
+import {
+  KNOWLEDGE_GRAPHQL_SDL,
+  clampInt,
+  clampOffset,
+  installJsonScalar,
+  mapJob,
+  mapJobRun,
+  mapPacket,
+  mapProjectionBundle,
+  mapProjectionTarget,
+  pickOperation,
+  toJobMode,
+  toPacketDetail,
+  toProjectionKind,
+} from '@pellux/goodvibes-sdk/platform/knowledge/graphql-schema';
+
+export interface KnowledgeGraphqlAccessProfile {
+  readonly operation: 'query' | 'mutation';
+  readonly requiredScopes: readonly string[];
+  readonly adminRequired: boolean;
+}
+
+export function inspectKnowledgeGraphqlAccess(
+  source: string,
+  operationName?: string,
+): KnowledgeGraphqlAccessProfile {
+  const document = parse(source);
+  const operation = pickOperation(document, operationName);
+  return operation === 'mutation'
+    ? { operation, requiredScopes: ['write:knowledge'], adminRequired: true }
+    : { operation, requiredScopes: ['read:knowledge'], adminRequired: false };
+}
+
+interface KnowledgeGraphqlContext {
+  readonly service: KnowledgeService;
+  readonly admin: boolean;
+  readonly scopes: readonly string[];
+}
+
+function assertWriteAccess(context: KnowledgeGraphqlContext): void {
+  if (!context.admin) {
+    throw new GraphQLError('Knowledge GraphQL mutation requires admin access.');
+  }
+  if (!context.scopes.includes('write:knowledge')) {
+    throw new GraphQLError('Knowledge GraphQL mutation requires write:knowledge.');
+  }
+}
+
+export interface KnowledgeGraphqlExecuteInput {
+  readonly query: string;
+  readonly operationName?: string;
+  readonly variables?: Record<string, unknown>;
+  readonly admin: boolean;
+  readonly scopes: readonly string[];
+}
+
+export class KnowledgeGraphqlService {
+  private static readonly schema = (() => {
+    const schema = buildSchema(KNOWLEDGE_GRAPHQL_SDL);
+    installJsonScalar(schema);
+    return schema;
+  })();
+
+  static readonly schemaSdl = printSchema(KnowledgeGraphqlService.schema);
+
+  constructor(private readonly service: KnowledgeService) {}
+
+  get schemaText(): string {
+    return KnowledgeGraphqlService.schemaSdl;
+  }
+
+  async execute(input: KnowledgeGraphqlExecuteInput) {
+    const rootValue = this.createRootValue();
+    const context: KnowledgeGraphqlContext = {
+      service: this.service,
+      admin: input.admin,
+      scopes: [...input.scopes],
+    };
+    const result = await graphql({
+      schema: KnowledgeGraphqlService.schema,
+      source: input.query,
+      rootValue,
+      contextValue: context,
+      variableValues: input.variables,
+      operationName: input.operationName,
+    });
+    return result;
+  }
+
+  private createRootValue() {
+    return {
+      status: async () => this.service.getStatus(),
+      sources: ({ limit }: { limit?: number }) => this.service.listSources(clampInt(limit, 100)),
+      nodes: ({ limit }: { limit?: number }) => this.service.listNodes(clampInt(limit, 100)),
+      issues: ({ limit }: { limit?: number }) => this.service.listIssues(clampInt(limit, 100)),
+      source: ({ id }: { id: string }) => this.service.listSources(10_000).find((source) => source.id === id) ?? null,
+      node: ({ id }: { id: string }) => this.service.listNodes(10_000).find((node) => node.id === id) ?? null,
+      issue: ({ id }: { id: string }) => this.service.listIssues(10_000).find((issue) => issue.id === id) ?? null,
+      item: ({ id }: { id: string }) => this.service.getItem(id),
+      items: ({ ids }: { ids: string[] }) => this.service.getItems(ids),
+      sourcesConnection: (args: {
+        limit?: number;
+        offset?: number;
+        status?: string;
+        connectorId?: string;
+        sourceType?: string;
+        tag?: string;
+        query?: string;
+      }) => this.service.querySources({
+        limit: clampInt(args.limit, 100),
+        offset: clampOffset(args.offset),
+        status: args.status,
+        connectorId: args.connectorId,
+        sourceType: args.sourceType,
+        tag: args.tag,
+        query: args.query,
+      }),
+      nodesConnection: (args: { limit?: number; offset?: number; kind?: string; status?: string; query?: string }) => this.service.queryNodes({
+        limit: clampInt(args.limit, 100),
+        offset: clampOffset(args.offset),
+        kind: args.kind,
+        status: args.status,
+        query: args.query,
+      }),
+      issuesConnection: (args: { limit?: number; offset?: number; severity?: string; status?: string; code?: string; query?: string }) => this.service.queryIssues({
+        limit: clampInt(args.limit, 100),
+        offset: clampOffset(args.offset),
+        severity: args.severity,
+        status: args.status,
+        code: args.code,
+        query: args.query,
+      }),
+      extractions: ({ limit, sourceId }: { limit?: number; sourceId?: string }) => this.service.listExtractions(clampInt(limit, 100), sourceId),
+      sourceExtraction: ({ sourceId }: { sourceId: string }) => this.service.getSourceExtraction(sourceId),
+      neighbors: ({ kind, id, relation, limit }: { kind: 'source' | 'node'; id: string; relation?: string; limit?: number }) => {
+        if (kind !== 'source' && kind !== 'node') {
+          throw new GraphQLError(`Unsupported knowledge neighbor kind: ${kind}`);
+        }
+        return this.service.getNeighbors(kind, id, { relation, limit: clampInt(limit, 20) });
+      },
+      search: ({ query, limit }: { query: string; limit?: number }) => this.service.search(query, clampInt(limit, 10)),
+      packet: async ({ task, writeScope, limit, detail, budgetLimit }: { task: string; writeScope?: string[]; limit?: number; detail?: string; budgetLimit?: number }) => mapPacket(await this.service.buildPacket(
+        task,
+        writeScope ?? [],
+        clampInt(limit, 6),
+        {
+          detail: toPacketDetail(detail),
+          ...(typeof budgetLimit === 'number' ? { budgetLimit } : {}),
+        },
+      )),
+      connectors: () => this.service.listConnectors(),
+      connector: ({ id }: { id: string }) => this.service.getConnector(id),
+      connectorDoctor: ({ id }: { id: string }) => this.service.doctorConnector(id),
+      projectionTargets: async ({ limit }: { limit?: number }) => (await this.service.listProjectionTargets(clampInt(limit, 25))).map((target) => mapProjectionTarget(target)),
+      projection: async ({ kind, id, limit }: { kind: string; id?: string; limit?: number }) => mapProjectionBundle(await this.service.renderProjection({
+        kind: toProjectionKind(kind),
+        id,
+        limit: clampInt(limit, 12),
+      })),
+      jobs: () => this.service.listJobs().map((job) => mapJob(job)),
+      job: ({ id }: { id: string }) => {
+        const job = this.service.getJob(id);
+        return job ? mapJob(job) : null;
+      },
+      jobRuns: ({ limit, jobId }: { limit?: number; jobId?: string }) => this.service.listJobRuns(clampInt(limit, 25), jobId).map((run) => mapJobRun(run)),
+      usage: ({ limit, targetKind, targetId, usageKind }: { limit?: number; targetKind?: 'source' | 'node' | 'issue'; targetId?: string; usageKind?: string }) => (
+        this.service.listUsageRecords(clampInt(limit, 100), {
+          ...(targetKind ? { targetKind } : {}),
+          ...(targetId ? { targetId } : {}),
+          ...(usageKind ? { usageKind: usageKind as 'search-hit' | 'packet-item' | 'item-open' | 'neighbor-open' | 'projection-read' | 'multimodal-writeback' } : {}),
+        })
+      ),
+      consolidationCandidates: ({ limit, status, subjectKind, subjectId }: { limit?: number; status?: string; subjectKind?: 'source' | 'node' | 'issue'; subjectId?: string }) => (
+        this.service.listConsolidationCandidates(clampInt(limit, 100), {
+          ...(status ? { status: status as 'open' | 'accepted' | 'rejected' | 'superseded' } : {}),
+          ...(subjectKind ? { subjectKind } : {}),
+          ...(subjectId ? { subjectId } : {}),
+        })
+      ),
+      consolidationCandidate: ({ id }: { id: string }) => this.service.getConsolidationCandidate(id),
+      consolidationReports: ({ limit }: { limit?: number }) => this.service.listConsolidationReports(clampInt(limit, 100)),
+      consolidationReport: ({ id }: { id: string }) => this.service.getConsolidationReport(id),
+      schedules: ({ limit }: { limit?: number }) => this.service.listSchedules(clampInt(limit, 100)),
+      schedule: ({ id }: { id: string }) => this.service.getSchedule(id),
+      ingestUrl: async (
+        args: {
+          url: string;
+          title?: string;
+          tags?: string[];
+          folderPath?: string;
+          sessionId?: string;
+          sourceType?: string;
+          connectorId?: string;
+          allowPrivateHosts?: boolean;
+          metadata?: Record<string, unknown>;
+        },
+        context: KnowledgeGraphqlContext,
+      ) => {
+        assertWriteAccess(context);
+        const result = await this.service.ingestUrl({
+          url: args.url,
+          title: args.title,
+          tags: args.tags,
+          folderPath: args.folderPath,
+          sessionId: args.sessionId,
+          sourceType: args.sourceType as Parameters<KnowledgeService['ingestUrl']>[0]['sourceType'],
+          connectorId: args.connectorId,
+          allowPrivateHosts: args.allowPrivateHosts,
+          metadata: args.metadata,
+        });
+        return result.source;
+      },
+      ingestArtifact: async (
+        args: {
+          artifactId?: string;
+          path?: string;
+          uri?: string;
+          title?: string;
+          tags?: string[];
+          folderPath?: string;
+          sessionId?: string;
+          sourceType?: string;
+          connectorId?: string;
+          allowPrivateHosts?: boolean;
+          metadata?: Record<string, unknown>;
+        },
+        context: KnowledgeGraphqlContext,
+      ) => {
+        assertWriteAccess(context);
+        const result = await this.service.ingestArtifact({
+          artifactId: args.artifactId,
+          path: args.path,
+          uri: args.uri,
+          title: args.title,
+          tags: args.tags,
+          folderPath: args.folderPath,
+          sessionId: args.sessionId,
+          sourceType: args.sourceType as Parameters<KnowledgeService['ingestArtifact']>[0]['sourceType'],
+          connectorId: args.connectorId,
+          allowPrivateHosts: args.allowPrivateHosts,
+          metadata: args.metadata,
+        });
+        return result.source;
+      },
+      importBookmarks: async (args: { path: string; sessionId?: string; allowPrivateHosts?: boolean }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.importBookmarksFromFile(args);
+      },
+      importUrls: async (args: { path: string; sessionId?: string; allowPrivateHosts?: boolean }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.importUrlsFromFile(args);
+      },
+      ingestConnector: async (
+        args: { connectorId: string; input?: unknown; content?: string; path?: string; sessionId?: string; allowPrivateHosts?: boolean },
+        context: KnowledgeGraphqlContext,
+      ) => {
+        assertWriteAccess(context);
+        return this.service.ingestConnectorInput(args);
+      },
+      lint: async (_args: Record<string, never>, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.lint();
+      },
+      reindex: async (_args: Record<string, never>, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.reindex();
+      },
+      runJob: async (args: { id: string; mode?: string; sourceIds?: string[]; limit?: number }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return mapJobRun(await this.service.runJob(args.id, {
+          ...(args.mode ? { mode: toJobMode(args.mode) } : {}),
+          ...(args.sourceIds ? { sourceIds: args.sourceIds } : {}),
+          ...(typeof args.limit === 'number' ? { limit: args.limit } : {}),
+        }));
+      },
+      decideCandidate: async (args: { id: string; decision: 'accept' | 'reject' | 'supersede'; decidedBy?: string; memoryClass?: string; scope?: string; detail?: string }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.decideConsolidationCandidate(args.id, args.decision, {
+          decidedBy: args.decidedBy,
+          memoryClass: args.memoryClass,
+          scope: args.scope,
+          detail: args.detail,
+        });
+      },
+      saveSchedule: async (args: { id?: string; jobId: string; label?: string; enabled?: boolean; schedule: Record<string, unknown> }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.saveSchedule({
+          id: args.id,
+          jobId: args.jobId,
+          label: args.label,
+          enabled: args.enabled,
+          schedule: args.schedule as unknown as Parameters<KnowledgeService['saveSchedule']>[0]['schedule'],
+        });
+      },
+      deleteSchedule: async (args: { id: string }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.deleteSchedule(args.id);
+      },
+      setScheduleEnabled: async (args: { id: string; enabled: boolean }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        return this.service.setScheduleEnabled(args.id, args.enabled);
+      },
+      materializeProjection: async (args: { kind: string; id?: string; limit?: number; filename?: string }, context: KnowledgeGraphqlContext) => {
+        assertWriteAccess(context);
+        const materialized = await this.service.materializeProjection({
+          kind: toProjectionKind(args.kind),
+          id: args.id,
+          limit: clampInt(args.limit, 12),
+          filename: args.filename,
+        });
+        return {
+          ...materialized,
+          bundle: mapProjectionBundle(materialized.bundle),
+        };
+      },
+    };
+  }
+}
+
+export function getKnowledgeGraphqlSchemaText(): string {
+  return KnowledgeGraphqlService.schemaSdl;
+}