@gmickel/gno 1.32.0 → 1.34.0

package/src/core/audit-contract.ts

@@ -0,0 +1,296 @@
+/** Versioned types and bounds for deterministic knowledge integrity audits. */
+
+import type { StorePort } from "../store/types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Versions & bounds
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const AUDIT_SCHEMA_VERSION = "1.0" as const;
+export const AUDIT_RULE_SET_VERSION = "1.0" as const;
+
+/** Default returned finding cap; totals remain exact when truncated. */
+export const AUDIT_DEFAULT_MAX_FINDINGS = 100;
+/** Hard upper bound for `--max-findings` / MCP maxFindings. */
+export const AUDIT_MAX_FINDINGS_LIMIT = 1000;
+export const AUDIT_MAX_EVIDENCE_PER_FINDING = 8;
+export const AUDIT_MAX_GUIDANCE_PER_FINDING = 4;
+export const AUDIT_MAX_EVIDENCE_DETAIL_CHARS = 512;
+export const AUDIT_MAX_MESSAGE_CHARS = 512;
+export const AUDIT_MAX_GUIDANCE_CHARS = 256;
+export const AUDIT_MAX_CODE_CHARS = 128;
+export const AUDIT_MAX_IDENTIFIER_CHARS = 2048;
+export const AUDIT_MAX_SCOPE_ITEMS = 256;
+export const AUDIT_MAX_SCOPE_VALUE_CHARS = 256;
+/** Bounded snapshot retries before `changed_during_audit`. */
+export const AUDIT_MAX_SNAPSHOT_ATTEMPTS = 2;
+
+export const AUDIT_CATEGORIES = ["links", "provenance", "freshness"] as const;
+export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
+
+export const AUDIT_RULE_STATUSES = [
+  "pass",
+  "fail",
+  "skip",
+  "unavailable",
+  "inconclusive",
+] as const;
+export type AuditRuleStatus = (typeof AUDIT_RULE_STATUSES)[number];
+
+export const AUDIT_REPORT_STATUSES = [
+  "complete",
+  "partial",
+  "changed_during_audit",
+  "failed",
+] as const;
+export type AuditReportStatus = (typeof AUDIT_REPORT_STATUSES)[number];
+
+export const AUDIT_EXIT_KINDS = [
+  "clean",
+  "findings",
+  "invalid",
+  "partial",
+  "runtime",
+] as const;
+export type AuditExitKind = (typeof AUDIT_EXIT_KINDS)[number];
+
+/**
+ * Process exit codes for `gno audit` / MCP surfaces.
+ * 0/1/2 align with global SUCCESS/VALIDATION/RUNTIME; 4/5 are audit-specific.
+ */
+export const AUDIT_EXIT_CODES = {
+  clean: 0,
+  invalid: 1,
+  runtime: 2,
+  findings: 4,
+  partial: 5,
+} as const satisfies Record<AuditExitKind, number>;
+
+export type AuditFindingSeverity = "error" | "warning" | "info";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// No-write port boundary
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read-only store methods permitted for audit snapshot/rule evaluation.
+ * Category tasks may narrow further; mutating StorePort methods are forbidden.
+ */
+export type AuditReadStorePort = Pick<
+  StorePort,
+  | "getActivationIndexSnapshot"
+  | "getCollections"
+  | "getStatus"
+  | "listDocuments"
+  | "listDocumentsPaginated"
+  | "getDocumentsByDocids"
+  | "getChunksBatch"
+  | "getContentBatch"
+>;
+
+/** Mutating StorePort method names that audits must never invoke. */
+export const AUDIT_FORBIDDEN_STORE_METHODS = [
+  "upsertDocument",
+  "deactivateDocument",
+  "deleteDocument",
+  "upsertChunks",
+  "deleteChunks",
+  "recordError",
+  "upsertActivationReceipt",
+  "createRetrievalTrace",
+  "withTransaction",
+  "syncCollections",
+  "cleanup",
+] as const;
+
+export type AuditForbiddenStoreMethod =
+  (typeof AUDIT_FORBIDDEN_STORE_METHODS)[number];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Report / finding shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuditScope {
+  /** Categories requested for this run. Empty means all categories. */
+  categories: AuditCategory[];
+  collections: string[];
+  /** Optional path/prefix filters (normalized, sorted). */
+  paths: string[];
+  /** Optional tag filters (normalized, sorted). */
+  tags: string[];
+  indexName: string;
+}
+
+export interface AuditCapabilitySnapshot {
+  indexReadable: boolean;
+  sourcesReadable: boolean;
+  linksGraphAvailable: boolean;
+  provenanceSchemaAvailable: boolean;
+  offline: true;
+  llmDisabled: true;
+}
+
+export interface AuditFingerprints {
+  /** Canonical config / rule-input fingerprint. */
+  config: string;
+  /** Source tree revision evidence fingerprint. */
+  source: string;
+  /** Index revision evidence fingerprint. */
+  index: string;
+  /** Active rule-set identity fingerprint. */
+  rules: string;
+}
+
+export interface AuditEvidence {
+  kind: string;
+  summary: string;
+  uri?: string;
+  path?: string;
+  detail?: string;
+}
+
+export interface AuditFinding {
+  /** Stable SHA-256 identity; survives traversal order. */
+  id: string;
+  ruleId: string;
+  category: AuditCategory;
+  severity: AuditFindingSeverity;
+  /** Normalized subject (typically gno:// URI or collection-relative path). */
+  subject: string;
+  /** Normalized location within the subject, or null. */
+  location: string | null;
+  message: string;
+  evidence: AuditEvidence[];
+  guidance: string[];
+  evidenceFingerprint: string;
+}
+
+export interface AuditRuleResult {
+  ruleId: string;
+  category: AuditCategory;
+  status: AuditRuleStatus;
+  message: string;
+  findings: AuditFinding[];
+  /** Exact findings before the bounded per-rule payload. */
+  findingCount: number;
+  examinedCount: number;
+  durationMs: number;
+  skipReason: string | null;
+}
+
+export interface AuditCounts {
+  rules: {
+    pass: number;
+    fail: number;
+    skip: number;
+    unavailable: number;
+    inconclusive: number;
+    total: number;
+  };
+  findings: {
+    /** Exact total before return-cap truncation. */
+    total: number;
+    /** Findings included in the report payload. */
+    returned: number;
+    truncated: boolean;
+  };
+  examined: {
+    documents: number;
+  };
+}
+
+export interface AuditTruncation {
+  findingsTruncated: boolean;
+  maxFindings: number;
+}
+
+export interface AuditTiming {
+  snapshotMs: number;
+  rulesMs: number;
+  totalMs: number;
+}
+
+export interface AuditVersions {
+  gno: string;
+  schema: typeof AUDIT_SCHEMA_VERSION;
+  ruleSet: typeof AUDIT_RULE_SET_VERSION;
+}
+
+export interface AuditReport {
+  schemaVersion: typeof AUDIT_SCHEMA_VERSION;
+  ruleSetVersion: typeof AUDIT_RULE_SET_VERSION;
+  status: AuditReportStatus;
+  scope: AuditScope;
+  capabilities: AuditCapabilitySnapshot;
+  fingerprints: AuditFingerprints;
+  versions: AuditVersions;
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+  rules: AuditRuleResult[];
+  findings: AuditFinding[];
+  counts: AuditCounts;
+  truncation: AuditTruncation;
+  timing: AuditTiming;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Draft / evaluator contracts (category rules plug in later)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuditFindingDraft {
+  subject: string;
+  location?: string | null;
+  severity: AuditFindingSeverity;
+  message: string;
+  evidence: AuditEvidence[];
+  guidance?: string[];
+}
+
+export interface AuditRuleContribution {
+  ruleId: string;
+  category: AuditCategory;
+  status: AuditRuleStatus;
+  message: string;
+  findings?: AuditFindingDraft[];
+  /** Exact findings before any evaluator-side payload cap. */
+  findingCount?: number;
+  examinedCount?: number;
+  durationMs?: number;
+  skipReason?: string | null;
+}
+
+export interface AuditRuleContext {
+  scope: AuditScope;
+  capabilities: AuditCapabilitySnapshot;
+  fingerprints: AuditFingerprints;
+  attempt: number;
+}
+
+export type AuditRuleEvaluator = (
+  ctx: AuditRuleContext
+) =>
+  | AuditRuleContribution
+  | AuditRuleContribution[]
+  | Promise<AuditRuleContribution | AuditRuleContribution[]>;
+
+export interface AuditFingerprintCapture {
+  (): AuditFingerprints | Promise<AuditFingerprints>;
+}
+
+export interface AuditRunInput {
+  scope: AuditScope;
+  capabilities: AuditCapabilitySnapshot;
+  captureFingerprints: AuditFingerprintCapture;
+  rules: readonly AuditRuleEvaluator[];
+  maxFindings?: number;
+  maxAttempts?: number;
+  gnoVersion?: string;
+  clock?: () => Date;
+  monotonicNow?: () => number;
+  signal?: AbortSignal;
+}
+
+export type AuditRunResult =
+  | { ok: true; report: AuditReport; exit: AuditExitKind }
+  | { ok: false; exit: "invalid"; error: string };

package/src/core/audit-freshness.ts

@@ -0,0 +1,233 @@
+/** Observable source/index freshness audit rules. */
+
+import type { AuditFindingDraft, AuditRuleContribution } from "./audit";
+
+import { compareAuditFindingDrafts } from "./audit";
+
+export const FRESHNESS_AUDIT_MAX_FINDINGS_PER_RULE = 1000;
+
+export interface AuditFreshnessDocument {
+  uri: string;
+  relPath: string;
+  contentType: string | null;
+  indexedSourceHash: string;
+  indexedSourceMtime: string;
+  indexedAt: string | null;
+  lastErrorCode: string | null;
+  source: {
+    state: "readable" | "missing" | "unreadable";
+    hash: string | null;
+    mtime: string | null;
+    /** Logical records use their physical container only for readability. */
+    byteComparable?: boolean;
+    changedDuringRead?: boolean;
+  };
+}
+
+export interface AuditAgePolicy {
+  maxAgeDays: number;
+  contentTypes?: readonly string[];
+}
+
+export interface AuditFreshnessOptions {
+  now: Date;
+  agePolicy?: AuditAgePolicy;
+  truncated?: boolean;
+}
+
+const finding = (input: {
+  document: AuditFreshnessDocument;
+  kind: string;
+  message: string;
+  detail: Record<string, unknown>;
+  severity?: "error" | "warning" | "info";
+  guidance: string;
+}): AuditFindingDraft => ({
+  subject: input.document.uri,
+  location: null,
+  severity: input.severity ?? "warning",
+  message: input.message,
+  evidence: [
+    {
+      kind: input.kind,
+      summary: input.message,
+      uri: input.document.uri,
+      path: input.document.relPath,
+      detail: JSON.stringify(input.detail),
+    },
+  ],
+  guidance: [input.guidance],
+});
+
+const rule = (input: {
+  ruleId: string;
+  findings: AuditFindingDraft[];
+  examinedCount: number;
+  unavailable?: boolean;
+  inconclusive?: boolean;
+  skipped?: boolean;
+  message: string;
+  reason?: string;
+}): AuditRuleContribution => ({
+  ruleId: input.ruleId,
+  category: "freshness",
+  status: input.inconclusive
+    ? "inconclusive"
+    : input.unavailable
+      ? "unavailable"
+      : input.skipped
+        ? "skip"
+        : input.findings.length > 0
+          ? "fail"
+          : "pass",
+  message: input.message,
+  findings: [...input.findings]
+    .sort(compareAuditFindingDrafts)
+    .slice(0, FRESHNESS_AUDIT_MAX_FINDINGS_PER_RULE),
+  findingCount: input.findings.length,
+  examinedCount: input.examinedCount,
+  skipReason: input.reason ?? null,
+});
+
+/** Age findings are policy signals only and do not claim factual incorrectness. */
+export const evaluateFreshnessAudit = (
+  documents: readonly AuditFreshnessDocument[],
+  options: AuditFreshnessOptions
+): AuditRuleContribution[] => {
+  const unavailable: AuditFindingDraft[] = [];
+  const drift: AuditFindingDraft[] = [];
+  const staleRevision: AuditFindingDraft[] = [];
+  const ageSignals: AuditFindingDraft[] = [];
+  let changedDuringRead = false;
+  const ageTypes = new Set(options.agePolicy?.contentTypes ?? []);
+  for (const document of documents) {
+    if (document.source.changedDuringRead) changedDuringRead = true;
+    if (document.source.state !== "readable") {
+      unavailable.push(
+        finding({
+          document,
+          kind: `source-${document.source.state}`,
+          message: `Source evidence is ${document.source.state}`,
+          detail: { state: document.source.state },
+          guidance: "Restore read access and re-run the audit",
+        })
+      );
+      continue;
+    }
+    if (
+      document.source.byteComparable !== false &&
+      document.source.hash !== null &&
+      document.source.hash !== document.indexedSourceHash
+    ) {
+      drift.push(
+        finding({
+          document,
+          kind: "source-index-hash-drift",
+          message: "Source bytes differ from the indexed revision",
+          detail: {
+            indexedHash: document.indexedSourceHash,
+            sourceHash: document.source.hash,
+          },
+          guidance: "Run gno index and inspect conversion errors",
+        })
+      );
+    }
+    if (!document.indexedAt || document.lastErrorCode) {
+      staleRevision.push(
+        finding({
+          document,
+          kind: "stale-indexed-revision",
+          message: document.lastErrorCode
+            ? "The latest indexing attempt recorded an error"
+            : "The document has no indexed-at revision evidence",
+          detail: {
+            indexedAt: document.indexedAt,
+            lastErrorCode: document.lastErrorCode,
+          },
+          guidance: "Run gno index and resolve the reported ingest error",
+        })
+      );
+    }
+    if (
+      options.agePolicy &&
+      (ageTypes.size === 0 ||
+        (document.contentType !== null && ageTypes.has(document.contentType)))
+    ) {
+      const timestamp = Date.parse(document.indexedSourceMtime);
+      const ageDays = (options.now.getTime() - timestamp) / 86_400_000;
+      if (Number.isFinite(ageDays) && ageDays > options.agePolicy.maxAgeDays) {
+        ageSignals.push(
+          finding({
+            document,
+            kind: "configured-age-signal",
+            message: `Source age exceeds the configured ${options.agePolicy.maxAgeDays}-day review signal`,
+            detail: {
+              ageDays: Math.floor(ageDays),
+              maxAgeDays: options.agePolicy.maxAgeDays,
+            },
+            severity: "info",
+            guidance:
+              "Review if useful; age is not evidence that the content is false",
+          })
+        );
+      }
+    }
+  }
+  const truncated = options.truncated === true;
+  const inconclusive = truncated || changedDuringRead;
+  const byteComparableCount = documents.filter(
+    ({ source }) => source.byteComparable !== false
+  ).length;
+  const excludedLogicalRecords = documents.length - byteComparableCount;
+  const reason = changedDuringRead
+    ? "source_changed_during_read"
+    : truncated
+      ? "snapshot_truncated"
+      : undefined;
+  return [
+    rule({
+      ruleId: "freshness.source-readable",
+      findings: unavailable,
+      examinedCount: documents.length,
+      unavailable: unavailable.length > 0 && !inconclusive,
+      inconclusive,
+      message: inconclusive
+        ? "Source readability evidence changed or was truncated"
+        : `${unavailable.length} sources are missing or unreadable`,
+      reason,
+    }),
+    rule({
+      ruleId: "freshness.source-index-drift",
+      findings: drift,
+      examinedCount: byteComparableCount,
+      inconclusive,
+      message: inconclusive
+        ? "Source/index drift evidence changed or was truncated"
+        : `${drift.length} source revisions differ from the index${excludedLogicalRecords > 0 ? `; ${excludedLogicalRecords} logical records excluded from byte comparison` : ""}`,
+      reason,
+    }),
+    rule({
+      ruleId: "freshness.index-revision",
+      findings: staleRevision,
+      examinedCount: documents.length,
+      inconclusive,
+      message: inconclusive
+        ? "Indexed revision evidence changed or was truncated"
+        : `${staleRevision.length} indexed revisions need attention`,
+      reason,
+    }),
+    rule({
+      ruleId: "freshness.configured-age-signal",
+      findings: ageSignals,
+      examinedCount: documents.length,
+      inconclusive,
+      skipped: !options.agePolicy,
+      message: !options.agePolicy
+        ? "No age review policy was configured"
+        : `${ageSignals.length} configured age review signals`,
+      reason:
+        reason ??
+        (!options.agePolicy ? "age_policy_not_configured" : undefined),
+    }),
+  ];
+};