waypath_health

Instructions

Implementation Reference

• src/facade/health.ts:182-244 (handler)

  Core health check logic: performs SQLite integrity check, FTS5 sync verification, temporal coherence analysis, source adapter probes (JCP + mempalace), and aggregates row counts/stale pages/pending reviews into a WaypathHealthResult.

  export function healthCheck(store: SqliteTruthKernelStorage, options: HealthCheckOptions = {}): WaypathHealthResult {
    const truthKernel = store.health();
    const integrityCheck = readIntegrityCheck(store);
    const sources = sourceStatus(options).sources;
    const jcpStatus = buildJcpStatus(
      getSourceStatusItem(sources, 'jarvis-memory-db'),
      options.jcpLiveReader ?? createJcpLiveReader(),
    );
    const mempalaceStatus = buildProbeStatus(getSourceStatusItem(sources, 'mempalace'), 'mempalace');
    const expectedRows = store.countTable('entities')
      + store.countTable('decisions')
      + store.countTable('preferences')
      + store.countTable('promoted_memories');
    const indexedRows = store.countTable('waypath_fts');
    const ftsSync = {
      ok: indexedRows === expectedRows,
      indexed_rows: indexedRows,
      expected_rows: expectedRows,
      missing_rows: Math.max(expectedRows - indexedRows, 0),
    };
    // valid_until is stored as ISO 8601 (e.g. '2026-04-16T10:30:00.000Z').
    // Pass current time in same format for correct string comparison.
    const nowIsoStr = new Date().toISOString();
    const tables = ['entities', 'decisions', 'preferences', 'relationships', 'promoted_memories'] as const;
    let expiredButActive = 0;
    for (const table of tables) {
      expiredButActive += store.get<{ count: number }>(
        `SELECT COUNT(*) AS count FROM ${table} WHERE valid_until IS NOT NULL AND valid_until < :now AND status = 'active'`,
        { now: nowIsoStr },
      )?.count ?? 0;
    }
    const temporalCoherence = {
      expired_but_active: expiredButActive,
      warning: expiredButActive > 0
        ? `${expiredButActive} records have valid_until in the past but are still active`
        : null,
    };
    const stalePages = store.get<{ count: number }>(
      `SELECT COUNT(*) AS count FROM knowledge_pages WHERE status = 'stale'`,
    )?.count ?? 0;
    const pendingReviews = store.get<{ count: number }>(
      `SELECT COUNT(*) AS count FROM promotion_candidates WHERE review_status IN ('pending', 'needs_more_evidence')`,
    )?.count ?? 0;
    const ok = truthKernel.ok && integrityCheck === 'ok' && ftsSync.ok;
  
    return {
      operation: 'health',
      status: 'ready',
      ok,
      truth_kernel: {
        ...truthKernel,
        integrity_check: integrityCheck,
      },
      fts_sync: ftsSync,
      stale_pages: stalePages,
      pending_reviews: pendingReviews,
      temporal_coherence: temporalCoherence,
      jcp_status: jcpStatus,
      mempalace_status: mempalaceStatus,
      db_size_bytes: dbFileSizeBytes(store.location),
      message: ok ? 'waypath health check passed' : 'waypath health check failed',
    };
  }

• src/contracts/types.ts:320-333 (schema)

  WaypathHealthResult interface defining the shape of the health check response including truth_kernel, fts_sync, stale_pages, pending_reviews, temporal_coherence, jcp_status, mempalace_status, and db_size_bytes.

  export interface WaypathHealthResult {
    operation: 'health';
    status: 'ready';
    ok: boolean;
    truth_kernel: WaypathTruthKernelStatus;
    fts_sync: WaypathFtsSyncStatus;
    stale_pages: number;
    pending_reviews: number;
    temporal_coherence: WaypathTemporalCoherenceStatus;
    jcp_status: WaypathSourceHealthStatus;
    mempalace_status: WaypathSourceHealthStatus;
    db_size_bytes: number;
    message: string;
  }

• src/mcp/tools.ts:308-320 (registration)

  MCP tool registration for 'waypath_health' including its description, empty inputSchema, and handler that delegates to facade.health().

  {
    name: 'waypath_health',
    description:
      'Read-only end-to-end health check: SQLite connectivity and migration version, FTS5 index sync status, source adapter probe results, and truth-kernel row counts. Safe to call any time and from any context. Use as a single diagnostic entrypoint before opening a support issue; for adapter-specific detail call waypath_source_status. Takes no parameters.',
    inputSchema: {
      type: 'object',
      properties: {},
      additionalProperties: false,
    },
    handler(_args, facade) {
      return facade.health();
    },
  },

• src/facade/facade.ts:226-231 (helper)

  Facade's health() method that imports and calls the healthCheck function from health.ts, passing the store and options.

  health(): WaypathHealthResult {
    return healthCheck(store, {
      sourceAdaptersEnabled: options.sourceAdaptersEnabled,
      jcpLiveReader,
    });
  },

• src/contracts/types.ts:300-306 (schema)

  Supporting type interfaces: WaypathTruthKernelStatus, WaypathFtsSyncStatus, and WaypathTemporalCoherenceStatus used within WaypathHealthResult.

  export interface WaypathTruthKernelStatus {
    ok: boolean;
    location: string;
    schema_version: number;
    message: string;
    integrity_check: string;
  }