@agentskit/doc-bridge 1.4.1 → 1.5.0

package/src/rules/engine.ts

@@ -0,0 +1,180 @@
+import { minimatch } from 'minimatch'
+
+import {
+  RuleIdSchema,
+  RuleSeveritySchema,
+  RulesConfigSchema,
+  type RuleId,
+  type RuleSeverity,
+  type RulesConfig,
+} from '../config/schema.js'
+import type { ReconciliationReportV1 } from '../schemas/knowledge.js'
+
+export type RuleMode = 'default' | 'recommended' | 'strict'
+
+export type RuleEngineOptions = {
+  readonly config?: RulesConfig
+  readonly preset?: RuleMode
+  readonly severity?: Partial<Record<RuleId, RuleSeverity>>
+  readonly ignore?: readonly RuleId[]
+  readonly criticalEntities?: readonly string[]
+  readonly criticalPaths?: readonly string[]
+  readonly warningThresholds?: Partial<Record<RuleId, number>>
+}
+
+export type RuleFinding = {
+  readonly id: string
+  readonly ruleId: RuleId
+  readonly code: string
+  readonly status: ReconciliationReportV1['diagnostics'][number]['status']
+  readonly severity: RuleSeverity
+  readonly message: string
+  readonly evidence: ReconciliationReportV1['diagnostics'][number]['evidence']
+  readonly entityIds?: readonly string[]
+  readonly relationIds?: readonly string[]
+  readonly remediation?: string
+  readonly sourceDiagnosticCode?: string
+}
+
+export type RuleEvaluationResult = {
+  readonly mode: RuleMode
+  readonly findings: readonly RuleFinding[]
+  readonly exitCode: 0 | 1
+}
+
+const diagnosticRules: Readonly<Record<string, RuleId>> = {
+  DOCUMENTATION_QUALITY: 'documentation-quality',
+  RELATION_UNDOCUMENTED: 'graph-undocumented-relation',
+  DECLARED_RELATION_STALE: 'declared-unobserved-relation',
+  UNRESOLVED_ENTITY_REFERENCE: 'unresolved-reference',
+  CONFLICTING_DECLARATIONS: 'conflicting-declaration',
+  RELATION_NOT_ANALYZED: 'not-analyzed-coverage',
+  STALE_DOCUMENTATION: 'stale-documentation',
+  FRESHNESS_FAILURE: 'freshness',
+  OWNERSHIP_GAP: 'ownership',
+  CENTRALITY_RISK: 'centrality-risk',
+  CRITICAL_PATH_RISK: 'critical-path-risk',
+}
+
+const defaultSeverity = (mode: RuleMode, ruleId: RuleId): RuleSeverity => {
+  if (mode === 'default') return 'info'
+  if (mode === 'strict') return ruleId === 'not-analyzed-coverage' ? 'warn' : 'error'
+  return ruleId === 'not-analyzed-coverage' ? 'info' : 'warn'
+}
+
+const resolvedOptions = (options: RuleEngineOptions): {
+  readonly mode: RuleMode
+  readonly severity: Partial<Record<RuleId, RuleSeverity>>
+  readonly ignore: ReadonlySet<RuleId>
+  readonly criticalEntities: readonly string[]
+  readonly criticalPaths: readonly string[]
+  readonly warningThresholds: Partial<Record<RuleId, number>>
+} => {
+  const config = RulesConfigSchema.parse(options.config ?? {})
+  const mode = options.preset ?? config.mode ?? 'default'
+  const severity = { ...config.severity, ...options.severity }
+  const ignore = new Set<RuleId>([...(config.ignore ?? []), ...(options.ignore ?? [])])
+  return {
+    mode,
+    severity,
+    ignore,
+    criticalEntities: options.criticalEntities ?? config.criticalEntities ?? [],
+    criticalPaths: options.criticalPaths ?? config.criticalPaths ?? [],
+    warningThresholds: { ...config.warningThresholds, ...options.warningThresholds },
+  }
+}
+
+const severityFor = (
+  ruleId: RuleId,
+  mode: RuleMode,
+  overrides: Partial<Record<RuleId, RuleSeverity>>,
+): RuleSeverity => overrides[ruleId] ?? defaultSeverity(mode, ruleId)
+
+const findingFromDiagnostic = (
+  diagnostic: ReconciliationReportV1['diagnostics'][number],
+  ruleId: RuleId,
+  severity: RuleSeverity,
+): RuleFinding => ({
+  id: `${diagnostic.id}:${ruleId}`,
+  ruleId,
+  code: ruleId,
+  status: diagnostic.status,
+  severity,
+  message: diagnostic.message,
+  evidence: diagnostic.evidence,
+  ...(diagnostic.entityIds ? { entityIds: diagnostic.entityIds } : {}),
+  ...(diagnostic.relationIds ? { relationIds: diagnostic.relationIds } : {}),
+  ...(diagnostic.remediation ? { remediation: diagnostic.remediation } : {}),
+  sourceDiagnosticCode: diagnostic.code,
+})
+
+const criticalFinding = (
+  finding: RuleFinding,
+  severity: RuleSeverity,
+  target: string,
+): RuleFinding => ({
+  ...finding,
+  id: `${finding.id}:critical:${target}`,
+  ruleId: 'critical-path-risk',
+  code: 'critical-path-risk',
+  severity,
+  message: `Critical path or entity is affected: ${target}. ${finding.message}`,
+})
+
+export const evaluateRules = (
+  report: ReconciliationReportV1,
+  options: RuleEngineOptions = {},
+): RuleEvaluationResult => {
+  const resolved = resolvedOptions(options)
+  const findings: RuleFinding[] = []
+
+  for (const diagnostic of [...report.diagnostics].sort((a, b) => a.id.localeCompare(b.id))) {
+    const ruleId = diagnosticRules[diagnostic.code]
+    if (!ruleId || resolved.ignore.has(ruleId)) continue
+    const severity = severityFor(ruleId, resolved.mode, resolved.severity)
+    if (severity !== 'off') findings.push(findingFromDiagnostic(diagnostic, ruleId, severity))
+  }
+
+  const criticalSeverity = severityFor('critical-path-risk', resolved.mode, resolved.severity)
+  const criticalEntitySet = new Set(resolved.criticalEntities)
+  for (const finding of [...findings]) {
+    const matchingEntity = (finding.entityIds ?? []).find((id) => criticalEntitySet.has(id))
+    if (matchingEntity && !resolved.ignore.has('critical-path-risk') && criticalSeverity !== 'off') {
+      findings.push(criticalFinding(finding, criticalSeverity, matchingEntity))
+    }
+    for (const path of resolved.criticalPaths) {
+      if (finding.evidence.some((item) => minimatch(item.path, path, { dot: true })) && !resolved.ignore.has('critical-path-risk') && criticalSeverity !== 'off') {
+        findings.push(criticalFinding(finding, criticalSeverity, path))
+      }
+    }
+  }
+
+  const centralityThreshold = resolved.warningThresholds['centrality-risk'] ?? 3
+  const centralitySeverity = severityFor('centrality-risk', resolved.mode, resolved.severity)
+  if (!resolved.ignore.has('centrality-risk') && centralitySeverity !== 'off') {
+    const counts = new Map<string, number>()
+    for (const finding of findings.filter((item) => item.ruleId === 'graph-undocumented-relation')) {
+      for (const entityId of finding.entityIds ?? []) counts.set(entityId, (counts.get(entityId) ?? 0) + 1)
+    }
+    for (const [entityId, count] of [...counts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      if (count < centralityThreshold || !criticalEntitySet.has(entityId)) continue
+      findings.push({
+        id: `centrality-risk:${entityId}`,
+        ruleId: 'centrality-risk',
+        code: 'centrality-risk',
+        status: 'unresolved',
+        severity: centralitySeverity,
+        message: `Critical entity has ${count} undocumented relation finding(s); static centrality is a review signal, not a runtime availability claim.`,
+        evidence: findings.filter((item) => item.ruleId === 'graph-undocumented-relation' && item.entityIds?.includes(entityId)).flatMap((item) => item.evidence),
+        entityIds: [entityId],
+        remediation: 'Review ownership, dependency boundaries, and runtime availability before declaring an SPOF.',
+      })
+    }
+  }
+
+  const sortedFindings = [...findings].sort((a, b) => a.id.localeCompare(b.id))
+  return { mode: resolved.mode, findings: sortedFindings, exitCode: sortedFindings.some((finding) => finding.severity === 'error') ? 1 : 0 }
+}
+
+export const parseRuleId = (value: string): RuleId => RuleIdSchema.parse(value)
+export const parseRuleSeverity = (value: string): RuleSeverity => RuleSeveritySchema.parse(value)

package/src/safety/repository.ts

@@ -0,0 +1,84 @@
+import { lstatSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+import { minimatch } from 'minimatch'
+
+export const DEFAULT_SAFETY_EXCLUDES = ['**/.git/**', '**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.doc-bridge/**', '**/.env', '**/.env.*', '**/*secret*', '**/*credential*', '**/*.pem', '**/*.key'] as const
+
+export type SafeWalkOptions = {
+  readonly extensions?: readonly string[]
+  readonly exclude?: readonly string[]
+  readonly maxFiles?: number
+  readonly maxBytes?: number
+  readonly maxTimeMs?: number
+  readonly maxMemoryMb?: number
+}
+
+export type SafeWalkResult = {
+  readonly files: readonly string[]
+  readonly incomplete: boolean
+  readonly reason?: string
+}
+
+export const containedPath = (root: string, candidate: string): string | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const unresolved = resolve(projectRoot, candidate)
+  const unresolvedRelative = relative(projectRoot, unresolved)
+  if (isAbsolute(unresolvedRelative) || unresolvedRelative === '..' || unresolvedRelative.startsWith(`..${sep}`)) return undefined
+  try {
+    const canonical = realpathSync.native(unresolved)
+    const canonicalRelative = relative(projectRoot, canonical)
+    return isAbsolute(canonicalRelative) || canonicalRelative === '..' || canonicalRelative.startsWith(`..${sep}`) ? undefined : canonical
+  } catch {
+    return unresolved
+  }
+}
+
+export const safeWalkFiles = (root: string, options: SafeWalkOptions = {}): SafeWalkResult => {
+  const projectRoot = resolve(root)
+  const extensions = options.extensions ?? []
+  const excludes = options.exclude ?? DEFAULT_SAFETY_EXCLUDES
+  const files: string[] = []
+  let bytes = 0
+  let reason: string | undefined
+  const started = Date.now()
+  const matchesExclude = (path: string): boolean => excludes.some((pattern) => minimatch(path, pattern, { dot: true }))
+  const visit = (directory: string): void => {
+    if (reason) return
+    if (options.maxTimeMs !== undefined && Date.now() - started >= options.maxTimeMs) { reason = `Repository scan exceeded the ${options.maxTimeMs} ms time limit.`; return }
+    if (options.maxMemoryMb !== undefined && process.memoryUsage().heapUsed > options.maxMemoryMb * 1024 * 1024) { reason = `Repository scan exceeded the ${options.maxMemoryMb} MiB memory limit.`; return }
+    let entries: string[]
+    try { entries = readdirSync(directory) } catch { return }
+    for (const name of entries.sort()) {
+      const absolute = resolve(directory, name)
+      const relativePath = relative(projectRoot, absolute).split(sep).join('/')
+      if (matchesExclude(relativePath) || name === '.git') continue
+      let stats
+      try { stats = lstatSync(absolute) } catch { continue }
+      if (stats.isSymbolicLink()) continue
+      if (stats.isDirectory()) { visit(absolute); if (reason) return; continue }
+      if (!stats.isFile() || (extensions.length > 0 && !extensions.some((extension) => name.endsWith(extension)))) continue
+      if (files.length >= (options.maxFiles ?? 10_000)) { reason = `Repository scan exceeded the ${options.maxFiles ?? 10_000} file limit.`; return }
+      bytes += statSync(absolute).size
+      if (options.maxBytes !== undefined && bytes > options.maxBytes) { reason = `Repository scan exceeded the ${options.maxBytes} byte limit.`; return }
+      files.push(absolute)
+    }
+  }
+  visit(projectRoot)
+  return { files: files.sort(), incomplete: reason !== undefined, ...(reason ? { reason } : {}) }
+}
+
+const SECRET_PATTERNS = [
+  /\b(?:sk|pk)[_-](?:live|test)[_-][A-Za-z0-9_-]{12,}\b/g,
+  /\b(?:ghp|github_pat|xox[baprs])_[A-Za-z0-9_-]{12,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /(?:password|passwd|secret|token|api[_-]?key)\s*[:=]\s*["']?[^\s,"']+/gi,
+]
+
+export const redactSecrets = (value: string): string => SECRET_PATTERNS.reduce((result, pattern) => result.replace(pattern, '[REDACTED]'), value)
+
+export const redactValue = (value: unknown): unknown => Array.isArray(value)
+  ? value.map(redactValue)
+  : value && typeof value === 'object'
+    ? Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, redactValue(item)]))
+    : typeof value === 'string' ? redactSecrets(value) : value

package/src/schemas/knowledge.ts

@@ -0,0 +1,315 @@
+import { z } from 'zod'
+
+export const KNOWLEDGE_SCHEMA_VERSION = 1 as const
+export const KNOWLEDGE_CONTENT_HASH_ALGO = 'sha256-normalized-v1' as const
+
+const hash = z.string().regex(/^[a-f0-9]{64}$/)
+const boundedString = (max: number) => z.string().min(1).max(max)
+
+export const ProvenanceSchema = z.enum(['observed', 'declared', 'proposed'])
+export type Provenance = z.infer<typeof ProvenanceSchema>
+
+export const FindingStatusSchema = z.enum([
+  'confirmed',
+  'undocumented',
+  'stale-or-unverified',
+  'conflict',
+  'unresolved',
+  'not-analyzed',
+])
+export type FindingStatus = z.infer<typeof FindingStatusSchema>
+
+export const DiagnosticSeveritySchema = z.enum(['off', 'info', 'warn', 'error'])
+export type DiagnosticSeverity = z.infer<typeof DiagnosticSeveritySchema>
+
+export const EvidenceSourceSchema = z.enum([
+  'code',
+  'configuration',
+  'documentation',
+  'agent',
+  'derived',
+])
+
+export const EvidenceSchema = z
+  .object({
+    source: EvidenceSourceSchema,
+    path: boundedString(512),
+    lineStart: z.number().int().positive().optional(),
+    lineEnd: z.number().int().positive().optional(),
+    contentHash: hash.optional(),
+    context: z.string().max(1_024).optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.lineStart !== undefined && value.lineEnd !== undefined && value.lineEnd < value.lineStart) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['lineEnd'],
+        message: 'Must be greater than or equal to lineStart',
+      })
+    }
+  })
+export type Evidence = z.infer<typeof EvidenceSchema>
+
+export const CoverageStatusSchema = z.enum(['complete', 'partial', 'not-analyzed'])
+
+export const CoverageSchema = z
+  .object({
+    analyzer: boundedString(128),
+    scope: boundedString(512),
+    status: CoverageStatusSchema,
+    reason: z.string().max(1_024).optional(),
+    evidence: z.array(EvidenceSchema).max(32).optional(),
+  })
+  .strict()
+export type Coverage = z.infer<typeof CoverageSchema>
+
+export const ProjectIdentitySchema = z
+  .object({
+    name: boundedString(128),
+    root: boundedString(512).optional(),
+  })
+  .strict()
+
+const ArtifactMetadata = {
+  schemaVersion: z.literal(KNOWLEDGE_SCHEMA_VERSION),
+  contentHash: hash,
+  contentHashAlgo: z.literal(KNOWLEDGE_CONTENT_HASH_ALGO),
+  project: ProjectIdentitySchema,
+  sourceRevision: boundedString(128),
+  sourceRevisionKind: z.enum(['git', 'content']),
+  configurationHash: hash,
+  pipelineVersion: boundedString(64),
+  analyzerVersions: z.record(boundedString(128), boundedString(64)),
+}
+
+export const EntitySchema = z
+  .object({
+    id: boundedString(256),
+    kind: boundedString(128),
+    name: boundedString(256),
+    path: boundedString(512).optional(),
+    aliases: z.array(boundedString(256)).max(32).optional(),
+    provenance: ProvenanceSchema,
+    evidence: z.array(EvidenceSchema).max(64),
+    metadata: z.record(z.unknown()).optional(),
+  })
+  .strict()
+export type KnowledgeEntity = z.infer<typeof EntitySchema>
+
+export const RelationSchema = z
+  .object({
+    id: boundedString(256),
+    kind: boundedString(128),
+    from: boundedString(256),
+    to: boundedString(256),
+    discriminator: boundedString(256).optional(),
+    provenance: ProvenanceSchema,
+    evidence: z.array(EvidenceSchema).max(64),
+    metadata: z.record(z.unknown()).optional(),
+  })
+  .strict()
+export type KnowledgeRelation = z.infer<typeof RelationSchema>
+
+export const DiscoverySnapshotV1Schema = z
+  .object({
+    type: z.literal('discovery-snapshot'),
+    ...ArtifactMetadata,
+    entities: z.array(EntitySchema).max(50_000),
+    relations: z.array(RelationSchema).max(100_000),
+    coverage: z.array(CoverageSchema).max(1_000),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const entityIds = new Set<string>()
+    for (const [index, entity] of value.entities.entries()) {
+      if (entityIds.has(entity.id)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['entities', index, 'id'], message: `Duplicate entity id: ${entity.id}` })
+      }
+      entityIds.add(entity.id)
+    }
+
+    const relationIds = new Set<string>()
+    for (const [index, relation] of value.relations.entries()) {
+      if (relationIds.has(relation.id)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['relations', index, 'id'], message: `Duplicate relation id: ${relation.id}` })
+      }
+      relationIds.add(relation.id)
+    }
+  })
+export type DiscoverySnapshotV1 = z.infer<typeof DiscoverySnapshotV1Schema>
+
+export const DiagnosticSchema = z
+  .object({
+    id: boundedString(256),
+    code: boundedString(128),
+    status: FindingStatusSchema,
+    severity: DiagnosticSeveritySchema,
+    message: boundedString(2_048),
+    evidence: z.array(EvidenceSchema).max(64),
+    entityIds: z.array(boundedString(256)).max(64).optional(),
+    relationIds: z.array(boundedString(256)).max(64).optional(),
+    remediation: z.string().max(2_048).optional(),
+  })
+  .strict()
+export type KnowledgeDiagnostic = z.infer<typeof DiagnosticSchema>
+
+export const ReconciliationReportV1Schema = z
+  .object({
+    type: z.literal('reconciliation-report'),
+    ...ArtifactMetadata,
+    snapshotHash: hash,
+    diagnostics: z.array(DiagnosticSchema).max(100_000),
+    summary: z
+      .object({
+        entityCount: z.number().int().nonnegative(),
+        relationCount: z.number().int().nonnegative(),
+        diagnosticCount: z.number().int().nonnegative(),
+      })
+      .strict(),
+  })
+  .strict()
+export type ReconciliationReportV1 = z.infer<typeof ReconciliationReportV1Schema>
+
+export const WorkflowStateSchema = z.enum([
+  'created',
+  'discovering',
+  'analyzed',
+  'compared',
+  'awaiting-agent',
+  'proposed',
+  'awaiting-approval',
+  'validating',
+  'delivered',
+  'failed',
+  'cancelled',
+  'stale',
+  'superseded',
+])
+export type WorkflowState = z.infer<typeof WorkflowStateSchema>
+
+export const WorkflowStepSchema = z
+  .object({
+    name: boundedString(128),
+    status: z.enum(['pending', 'running', 'completed', 'failed', 'skipped']),
+    inputHash: hash,
+    outputHash: hash.optional(),
+    artifactRefs: z.array(boundedString(512)).max(32).optional(),
+  })
+  .strict()
+export type WorkflowStep = z.infer<typeof WorkflowStepSchema>
+
+export const WorkflowTransitionSchema = z
+  .object({
+    from: WorkflowStateSchema.nullable(),
+    to: WorkflowStateSchema,
+    at: z.string().datetime(),
+    reason: z.string().max(1_024).optional(),
+  })
+  .strict()
+export type WorkflowTransition = z.infer<typeof WorkflowTransitionSchema>
+
+export const WorkflowRunV1Schema = z
+  .object({
+    type: z.literal('workflow-run'),
+    ...ArtifactMetadata,
+    runId: boundedString(128),
+    state: WorkflowStateSchema,
+    steps: z.array(WorkflowStepSchema).max(32),
+    transitions: z.array(WorkflowTransitionSchema).max(1_000),
+    artifactRefs: z.array(boundedString(512)).max(128),
+  })
+  .strict()
+export type WorkflowRunV1 = z.infer<typeof WorkflowRunV1Schema>
+
+export const ProposalOriginSchema = z
+  .object({
+    kind: z.enum(['registry-agent', 'manual', 'deterministic']),
+    id: boundedString(256).optional(),
+    version: boundedString(64).optional(),
+    provider: boundedString(128).optional(),
+    model: boundedString(256).optional(),
+    capabilities: z.array(boundedString(128)).max(32).optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.kind === 'registry-agent' && value.id === undefined) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ['id'], message: 'Registry agent origin requires an id' })
+    }
+  })
+
+export const AgentProposalV1Schema = z
+  .object({
+    type: z.literal('agent-proposal'),
+    ...ArtifactMetadata,
+    proposalId: boundedString(128),
+    baseSnapshotHash: hash,
+    baseReportHash: hash,
+    relatedDiagnosticIds: z.array(boundedString(256)).max(64),
+    rationale: boundedString(4_000),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(EvidenceSchema).max(128),
+    intendedChanges: z.array(boundedString(4_000)).max(64),
+    origin: ProposalOriginSchema,
+    checks: z.array(boundedString(512)).max(32),
+  })
+  .strict()
+export type AgentProposalV1 = z.infer<typeof AgentProposalV1Schema>
+
+export const FixProposalStatusSchema = z.enum(['proposed', 'approved', 'rejected', 'stale', 'applied', 'failed'])
+
+export const AffectedFileSchema = z
+  .object({
+    path: boundedString(512),
+    contentHash: hash,
+  })
+  .strict()
+
+export const FixChangeSchema = z
+  .object({
+    path: boundedString(512),
+    before: z.string().max(100_000),
+    after: z.string().max(100_000),
+  })
+  .strict()
+export type FixChange = z.infer<typeof FixChangeSchema>
+
+export const FixProposalV1Schema = z
+  .object({
+    type: z.literal('fix-proposal'),
+    ...ArtifactMetadata,
+    proposalId: boundedString(128),
+    baseRevision: boundedString(128),
+    affectedFiles: z.array(AffectedFileSchema).max(256),
+    changes: z.array(FixChangeSchema).max(256).optional(),
+    preconditions: z.array(boundedString(2_048)).max(64),
+    diff: boundedString(100_000),
+    postconditions: z.array(boundedString(2_048)).max(64),
+    approval: z
+      .object({
+        proposalHash: hash,
+        approvedAt: z.string().datetime(),
+        approvedBy: boundedString(256),
+      })
+      .strict()
+      .optional(),
+    status: FixProposalStatusSchema,
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if ((value.status === 'approved' || value.status === 'applied') && value.approval === undefined) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['approval'],
+        message: `Fix proposal status ${value.status} requires an approval record`,
+      })
+    }
+  })
+export type FixProposalV1 = z.infer<typeof FixProposalV1Schema>
+
+export type KnowledgeArtifactV1 =
+  | DiscoverySnapshotV1
+  | ReconciliationReportV1
+  | WorkflowRunV1
+  | AgentProposalV1
+  | FixProposalV1

package/src/validate.ts

@@ -14,6 +14,18 @@ import {
   MemoryCandidateV1Schema,
   type MemoryCandidateV1,
 } from './schemas/memory-candidate.js'
+import {
+  AgentProposalV1Schema,
+  DiscoverySnapshotV1Schema,
+  FixProposalV1Schema,
+  ReconciliationReportV1Schema,
+  WorkflowRunV1Schema,
+  type AgentProposalV1,
+  type DiscoverySnapshotV1,
+  type FixProposalV1,
+  type ReconciliationReportV1,
+  type WorkflowRunV1,
+} from './schemas/knowledge.js'
 
 export type ParseIssue = {
   readonly path: string
@@ -56,6 +68,18 @@ export const parseDocBridgeIndex = (input: unknown): DocBridgeIndexV1 =>
 export const parseMemoryCandidate = (input: unknown): MemoryCandidateV1 =>
   MemoryCandidateV1Schema.parse(input)
 
+export const parseDiscoverySnapshot = (input: unknown): DiscoverySnapshotV1 =>
+  DiscoverySnapshotV1Schema.parse(input)
+
+export const parseReconciliationReport = (input: unknown): ReconciliationReportV1 =>
+  ReconciliationReportV1Schema.parse(input)
+
+export const parseWorkflowRun = (input: unknown): WorkflowRunV1 => WorkflowRunV1Schema.parse(input)
+
+export const parseAgentProposal = (input: unknown): AgentProposalV1 => AgentProposalV1Schema.parse(input)
+
+export const parseFixProposal = (input: unknown): FixProposalV1 => FixProposalV1Schema.parse(input)
+
 export const parseDocBridgeConfig = (input: unknown): DocBridgeConfigV1 => {
   const result = DocBridgeConfigV1Schema.safeParse(input)
   if (!result.success) {

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.4.1'
+export const PACKAGE_VERSION = '1.5.0'