@nomos-arc/arc 0.1.0

package/src/core/budget.ts

@@ -0,0 +1,119 @@
+import * as path from 'path';
+import type { TaskState, NomosConfig } from '../types/index.js';
+
+// RT2-4.3 fix: Token estimation returns separate input/output counts.
+// The char/4 heuristic is rough but splitting it correctly applies
+// the right pricing rate to each component.
+export interface TokenEstimate {
+  input_tokens: number;
+  output_tokens: number;
+  total: number;
+}
+
+/**
+ * ROUGH ESTIMATE: Divides character count by 4.
+ * RT2-4.3 fix: Returns SEPARATE input and output token estimates so that
+ * calculateCost() can apply the correct rate to each. The char/4 heuristic
+ * still underestimates for CJK text (~1 char per 1-2 tokens), but splitting
+ * input/output eliminates the ~3x pricing error from applying a flat rate.
+ * Returns tokens_source: 'estimated' — callers should label this in display output.
+ */
+export function estimateTokens(prompt: string, output: string): TokenEstimate {
+  const input_tokens = Math.ceil(prompt.length / 4);
+  const output_tokens = Math.ceil(output.length / 4);
+  return { input_tokens, output_tokens, total: input_tokens + output_tokens };
+}
+
+/**
+ * Extracts the token count from the binary's output using the configured regex pattern.
+ * RT2-4.3 fix: Returns a TokenEstimate with separate input/output when the pattern
+ * captures two groups (e.g., "Input: (\d+).*Output: (\d+)"). Falls back to total-only
+ * (split 90/10 input/output as a heuristic) when only one group is captured.
+ * Returns null if the pattern is null or does not match.
+ */
+export function parseTokensFromOutput(
+  output: string,
+  usagePattern: string | null,
+): TokenEstimate | null {
+  if (!usagePattern) return null;
+  const match = output.match(new RegExp(usagePattern));
+  if (!match?.[1]) return null;
+
+  if (match[2]) {
+    // Pattern captured both input and output groups
+    const input_tokens = parseInt(match[1], 10);
+    const output_tokens = parseInt(match[2], 10);
+    if (isNaN(input_tokens) || isNaN(output_tokens)) return null;
+    return { input_tokens, output_tokens, total: input_tokens + output_tokens };
+  }
+
+  // Single group — total only. Apply 90/10 heuristic split for cost estimation.
+  const total = parseInt(match[1], 10);
+  if (isNaN(total)) return null;
+  const input_tokens = Math.round(total * 0.9);
+  const output_tokens = total - input_tokens;
+  return { input_tokens, output_tokens, total };
+}
+
+/**
+ * RT2-4.3 fix: Cost calculation with separate input/output rates.
+ * costMap keys use basename of the binary cmd (e.g., 'claude', 'codex').
+ * The previous version used the raw binaryCmd as the key — if cmd was an
+ * absolute path ('/usr/local/bin/claude') or 'npx', lookup returned undefined
+ * and cost tracking silently stopped.
+ *
+ * Rate structure: costMap values are objects with input/output rates per 1K tokens.
+ * For backward compatibility, a plain number is treated as the output rate
+ * with input rate at 1/5th (the typical Claude input/output ratio).
+ */
+export function calculateCost(
+  tokens: TokenEstimate,
+  binaryCmd: string,
+  costMap: Record<string, number | { input: number; output: number }>,
+): number {
+  // RT2-4.3 fix: normalize binaryCmd to basename for reliable map lookup.
+  // '/usr/local/bin/claude' → 'claude', 'npx' → 'npx'
+  const key = path.basename(binaryCmd);
+  const rateEntry = costMap[key];
+  if (rateEntry === undefined) return 0;
+
+  let inputRate: number;
+  let outputRate: number;
+  if (typeof rateEntry === 'number') {
+    // Backward compat: plain number = output rate; input = 1/5th
+    outputRate = rateEntry;
+    inputRate = rateEntry / 5;
+  } else {
+    inputRate = rateEntry.input;
+    outputRate = rateEntry.output;
+  }
+
+  const inputCost = (tokens.input_tokens / 1000) * inputRate;
+  const outputCost = (tokens.output_tokens / 1000) * outputRate;
+  return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000;
+}
+
+export function checkBudget(
+  state: TaskState,
+  config: NomosConfig,
+): { allowed: boolean; warning?: string; error?: string } {
+  const { tokens_used } = state.budget;
+  const { max_tokens_per_task, warn_at_percent } = config.budget;
+  if (tokens_used >= max_tokens_per_task) {
+    return {
+      allowed: false,
+      error: `Token budget exceeded for task "${state.task_id}". ` +
+        `Used: ${tokens_used} / ${max_tokens_per_task}. ` +
+        `Run: arc plan ${state.task_id} --extend-budget to increase limit.`,
+    };
+  }
+  const warnThreshold = (warn_at_percent / 100) * max_tokens_per_task;
+  if (tokens_used >= warnThreshold) {
+    const pct = Math.round((tokens_used / max_tokens_per_task) * 100);
+    return {
+      allowed: true,
+      warning: `Task "${state.task_id}" at ${pct}% of token budget (${tokens_used} / ${max_tokens_per_task}).`,
+    };
+  }
+  return { allowed: true };
+}

package/src/core/certificate.ts

@@ -0,0 +1,502 @@
+import { createHash } from 'crypto';
+import { z } from 'zod';
+import { NomosError } from './errors.js';
+import type {
+  TaskState,
+  TaskStatus,
+  HistoryEntry,
+  ReviewIssue,
+  CertificatePayload,
+  CertificateIteration,
+  VerificationResult,
+  VerificationCheck,
+} from '../types/index.js';
+
+// ── Package version (used in certificate generator field) ────────────────────
+
+// Read from package.json at build time isn't worth a dynamic import;
+// keep in sync manually. Bump when releasing.
+const GENERATOR_VERSION = 'nomos-arc@0.1.0';
+
+// ── Eligible statuses for certificate generation ─────────────────────────────
+
+const ELIGIBLE_STATUSES: TaskStatus[] = ['approved', 'merged'];
+
+// ── Zod schema for certificate validation (--verify) ─────────────────────────
+
+const ReviewIssueSchema = z.object({
+  severity: z.enum(['high', 'medium', 'low']),
+  category: z.enum(['security', 'performance', 'architecture', 'correctness', 'maintainability']),
+  description: z.string(),
+  suggestion: z.string(),
+});
+
+const IterationTokensSchema = z.object({
+  input: z.number().nonnegative(),
+  output: z.number().nonnegative(),
+  source: z.enum(['metered', 'estimated']),
+});
+
+const PlanningEntrySchema = z.object({
+  binary: z.string(),
+  mode: z.enum(['supervised', 'auto', 'dry-run']),
+  started_at: z.string().datetime(),
+  completed_at: z.string().datetime(),
+  output_hash: z.string(),
+  tokens: IterationTokensSchema,
+  rules_snapshot: z.array(z.string()),
+});
+
+const ReviewEntrySchema = z.object({
+  binary: z.string(),
+  mode: z.enum(['supervised', 'auto', 'dry-run']),
+  started_at: z.string().datetime(),
+  completed_at: z.string().datetime(),
+  output_hash: z.string(),
+  tokens: IterationTokensSchema,
+  score: z.number().min(0).max(1),
+  issues: z.array(ReviewIssueSchema),
+  summary: z.string(),
+});
+
+const CertificateIterationSchema = z.object({
+  version: z.number().int().nonnegative(),
+  planning: PlanningEntrySchema,
+  review: ReviewEntrySchema.nullable(),
+});
+
+const CertificatePayloadSchema = z.object({
+  certificate_version: z.literal(1),
+  generated_at: z.string().datetime(),
+  generator: z.string(),
+  task_id: z.string(),
+  task_status: z.enum([
+    'init', 'planning', 'pending_review', 'reviewing',
+    'refinement', 'approved', 'merged', 'discarded',
+    'failed', 'merge_conflict', 'stalled',
+  ]),
+  created_at: z.string().datetime(),
+  completed_at: z.string().datetime(),
+  repository: z.object({
+    base_commit: z.string(),
+    shadow_branch: z.string(),
+    branch_status: z.enum(['active', 'merged', 'discarded']),
+  }),
+  models: z.object({
+    planner: z.string(),
+    reviewer: z.string(),
+  }),
+  rules: z.object({
+    files: z.array(z.string()),
+    rules_hash: z.string(),
+  }),
+  iterations: z.array(CertificateIterationSchema),
+  final_review: z.object({
+    score: z.number().min(0).max(1),
+    summary: z.string(),
+    issues: z.array(ReviewIssueSchema),
+    approval_reason: z.enum(['score_threshold', 'max_iterations_reached']),
+  }),
+  budget: z.object({
+    total_tokens: z.number().nonnegative(),
+    estimated_cost_usd: z.number().nonnegative(),
+    token_breakdown: z.object({
+      input_tokens: z.number().nonnegative(),
+      output_tokens: z.number().nonnegative(),
+    }),
+  }),
+  integrity: z.object({
+    chain_hash: z.string(),
+    entry_hashes: z.array(z.string()),
+    canonical_entries: z.array(z.string()),
+    chain_algorithm: z.literal('sha256-sequential'),
+  }),
+  certificate_hash: z.string(),
+});
+
+// ── Canonical entry serialization ────────────────────────────────────────────
+// Deterministic JSON with fixed key order. Excludes raw_output (large/sensitive)
+// but includes output_hash which binds it cryptographically.
+
+function canonicalEntry(entry: HistoryEntry): string {
+  return JSON.stringify({
+    version: entry.version,
+    step: entry.step,
+    mode: entry.mode,
+    binary: entry.binary,
+    started_at: entry.started_at,
+    completed_at: entry.completed_at,
+    output_hash: entry.output_hash,
+    input_tokens: entry.input_tokens,
+    output_tokens: entry.output_tokens,
+    rules_snapshot: entry.rules_snapshot,
+    review_score: entry.review?.score ?? null,
+    review_summary: entry.review?.summary ?? null,
+  });
+}
+
+function sha256(data: string): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+// ── CertificateEngine ───────────────────────────────────────────────────────
+
+export class CertificateEngine {
+
+  /**
+   * Compute the sequential Merkle-like chain hash over history entries.
+   * H_0 = SHA-256(canonical(entry_0))
+   * H_n = SHA-256(H_{n-1} || canonical(entry_n))
+   */
+  computeChainHash(history: HistoryEntry[]): { chainHash: string; canonicalEntries: string[] } {
+    if (history.length === 0) {
+      const empty = sha256('');
+      return { chainHash: `sha256:${empty}`, canonicalEntries: [] };
+    }
+
+    const canonicalEntries: string[] = [];
+    let currentHash = '';
+
+    for (let i = 0; i < history.length; i++) {
+      const canonical = canonicalEntry(history[i]!);
+      canonicalEntries.push(canonical);
+
+      if (i === 0) {
+        currentHash = sha256(canonical);
+      } else {
+        currentHash = sha256(currentHash + canonical);
+      }
+    }
+
+    return { chainHash: `sha256:${currentHash}`, canonicalEntries };
+  }
+
+  /**
+   * Re-compute chain hash from stored canonical entries (used during verification).
+   */
+  recomputeChainFromCanonical(canonicalEntries: string[]): string {
+    if (canonicalEntries.length === 0) {
+      return `sha256:${sha256('')}`;
+    }
+
+    let currentHash = '';
+    for (let i = 0; i < canonicalEntries.length; i++) {
+      if (i === 0) {
+        currentHash = sha256(canonicalEntries[i]!);
+      } else {
+        currentHash = sha256(currentHash + canonicalEntries[i]!);
+      }
+    }
+
+    return `sha256:${currentHash}`;
+  }
+
+  /**
+   * Generate a Certificate of AI Engineering Integrity from a completed task state.
+   */
+  generate(state: TaskState): CertificatePayload {
+    // Precondition: task must be approved or merged
+    if (!ELIGIBLE_STATUSES.includes(state.meta.status)) {
+      throw new NomosError(
+        'certificate_not_eligible',
+        `Cannot generate certificate for task "${state.task_id}" in status "${state.meta.status}". ` +
+        `Task must be in one of: [${ELIGIBLE_STATUSES.join(', ')}]`,
+      );
+    }
+
+    // Precondition: must have at least one plan + one review
+    const planEntries = state.history.filter(e => e.step === 'planning');
+    const reviewEntries = state.history.filter(e => e.step === 'reviewing');
+    if (planEntries.length === 0 || reviewEntries.length === 0) {
+      throw new NomosError(
+        'certificate_not_eligible',
+        `Cannot generate certificate for task "${state.task_id}": ` +
+        `requires at least one planning and one reviewing entry in history`,
+      );
+    }
+
+    // Group history entries into iterations by version
+    const iterations = this.groupIterations(state.history);
+
+    // Extract final review
+    const lastReviewEntry = reviewEntries[reviewEntries.length - 1]!;
+    if (!lastReviewEntry.review) {
+      throw new NomosError(
+        'certificate_not_eligible',
+        `Cannot generate certificate for task "${state.task_id}": ` +
+        `last review entry has no review result`,
+      );
+    }
+
+    // Compute chain hash
+    const { chainHash, canonicalEntries } = this.computeChainHash(state.history);
+    const entryHashes = state.history.map(e => e.output_hash);
+
+    // Sum token breakdown
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    for (const entry of state.history) {
+      totalInputTokens += entry.input_tokens;
+      totalOutputTokens += entry.output_tokens;
+    }
+
+    // Completed at = last history entry's completed_at
+    const completedAt = state.history[state.history.length - 1]!.completed_at;
+
+    // Build payload (without certificate_hash)
+    const payload: Omit<CertificatePayload, 'certificate_hash'> = {
+      certificate_version: 1,
+      generated_at: new Date().toISOString(),
+      generator: GENERATOR_VERSION,
+
+      task_id: state.task_id,
+      task_status: state.meta.status,
+      created_at: state.meta.created_at,
+      completed_at: completedAt,
+
+      repository: {
+        base_commit: state.shadow_branch.base_commit,
+        shadow_branch: state.shadow_branch.branch,
+        branch_status: state.shadow_branch.status,
+      },
+
+      models: {
+        planner: state.orchestration.planner_bin,
+        reviewer: state.orchestration.reviewer_bin,
+      },
+
+      rules: {
+        files: state.context.rules,
+        rules_hash: state.context.rules_hash,
+      },
+
+      iterations,
+
+      final_review: {
+        score: lastReviewEntry.review.score,
+        summary: lastReviewEntry.review.summary,
+        issues: lastReviewEntry.review.issues,
+        approval_reason: state.meta.approval_reason ?? 'score_threshold',
+      },
+
+      budget: {
+        total_tokens: state.budget.tokens_used,
+        estimated_cost_usd: state.budget.estimated_cost_usd,
+        token_breakdown: {
+          input_tokens: totalInputTokens,
+          output_tokens: totalOutputTokens,
+        },
+      },
+
+      integrity: {
+        chain_hash: chainHash,
+        entry_hashes: entryHashes,
+        canonical_entries: canonicalEntries,
+        chain_algorithm: 'sha256-sequential',
+      },
+    };
+
+    // Self-seal: compute certificate_hash over the payload
+    const payloadJson = JSON.stringify(payload, null, 2);
+    const certificateHash = `sha256:${sha256(payloadJson)}`;
+
+    return { ...payload, certificate_hash: certificateHash };
+  }
+
+  /**
+   * Verify a certificate's integrity. Returns detailed check results.
+   */
+  verify(certificate: CertificatePayload): VerificationResult {
+    const checks: VerificationCheck[] = [];
+
+    // Check 1: Status validity
+    checks.push(this.checkStatusValidity(certificate));
+
+    // Check 2: Review completeness
+    checks.push(this.checkReviewCompleteness(certificate));
+
+    // Check 3: Certificate self-hash
+    checks.push(this.checkCertificateHash(certificate));
+
+    // Check 4: Chain hash
+    checks.push(this.checkChainHash(certificate));
+
+    // Check 5: Entry hash consistency
+    checks.push(this.checkEntryHashConsistency(certificate));
+
+    return {
+      valid: checks.every(c => c.passed),
+      checks,
+    };
+  }
+
+  /**
+   * Parse and validate a certificate JSON string. Throws on invalid structure.
+   */
+  parse(json: string): CertificatePayload {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(json);
+    } catch {
+      throw new NomosError('certificate_invalid', 'Certificate file is not valid JSON');
+    }
+
+    const result = CertificatePayloadSchema.safeParse(raw);
+    if (!result.success) {
+      const issues = result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ');
+      throw new NomosError('certificate_invalid', `Certificate validation failed: ${issues}`);
+    }
+
+    return result.data as CertificatePayload;
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private groupIterations(history: HistoryEntry[]): CertificateIteration[] {
+    const versionMap = new Map<number, { planning?: HistoryEntry; review?: HistoryEntry }>();
+
+    for (const entry of history) {
+      if (!versionMap.has(entry.version)) {
+        versionMap.set(entry.version, {});
+      }
+      const group = versionMap.get(entry.version)!;
+      if (entry.step === 'planning') {
+        group.planning = entry;
+      } else {
+        group.review = entry;
+      }
+    }
+
+    const iterations: CertificateIteration[] = [];
+    const sortedVersions = [...versionMap.keys()].sort((a, b) => a - b);
+
+    for (const version of sortedVersions) {
+      const group = versionMap.get(version)!;
+      if (!group.planning) continue; // skip orphan review entries
+
+      iterations.push({
+        version,
+        planning: {
+          binary: group.planning.binary,
+          mode: group.planning.mode,
+          started_at: group.planning.started_at,
+          completed_at: group.planning.completed_at,
+          output_hash: group.planning.output_hash,
+          tokens: {
+            input: group.planning.input_tokens,
+            output: group.planning.output_tokens,
+            source: group.planning.tokens_source,
+          },
+          rules_snapshot: group.planning.rules_snapshot,
+        },
+        review: group.review ? {
+          binary: group.review.binary,
+          mode: group.review.mode,
+          started_at: group.review.started_at,
+          completed_at: group.review.completed_at,
+          output_hash: group.review.output_hash,
+          tokens: {
+            input: group.review.input_tokens,
+            output: group.review.output_tokens,
+            source: group.review.tokens_source,
+          },
+          score: group.review.review?.score ?? 0,
+          issues: group.review.review?.issues ?? [],
+          summary: group.review.review?.summary ?? '',
+        } : null,
+      });
+    }
+
+    return iterations;
+  }
+
+  private checkStatusValidity(cert: CertificatePayload): VerificationCheck {
+    const passed = ELIGIBLE_STATUSES.includes(cert.task_status);
+    return {
+      name: 'status_validity',
+      passed,
+      detail: passed
+        ? `Task status "${cert.task_status}" is eligible for certification`
+        : `Task status "${cert.task_status}" is not eligible. Expected: [${ELIGIBLE_STATUSES.join(', ')}]`,
+    };
+  }
+
+  private checkReviewCompleteness(cert: CertificatePayload): VerificationCheck {
+    const hasReview = cert.final_review.score >= 0 && cert.final_review.summary.length > 0;
+    return {
+      name: 'review_completeness',
+      passed: hasReview,
+      detail: hasReview
+        ? `Final review present with score ${cert.final_review.score}`
+        : 'Final review is missing or incomplete',
+    };
+  }
+
+  private checkCertificateHash(cert: CertificatePayload): VerificationCheck {
+    // Remove certificate_hash, re-serialize, re-hash
+    const { certificate_hash, ...payloadWithoutHash } = cert;
+    const recomputed = `sha256:${sha256(JSON.stringify(payloadWithoutHash, null, 2))}`;
+    const passed = recomputed === certificate_hash;
+    return {
+      name: 'certificate_hash',
+      passed,
+      detail: passed
+        ? 'Certificate self-hash is valid — payload has not been modified'
+        : `Certificate hash mismatch. Expected ${certificate_hash}, computed ${recomputed}`,
+    };
+  }
+
+  private checkChainHash(cert: CertificatePayload): VerificationCheck {
+    const recomputed = this.recomputeChainFromCanonical(cert.integrity.canonical_entries);
+    const passed = recomputed === cert.integrity.chain_hash;
+    return {
+      name: 'chain_hash',
+      passed,
+      detail: passed
+        ? 'Chain hash is valid — history entries have not been tampered with'
+        : `Chain hash mismatch. Expected ${cert.integrity.chain_hash}, computed ${recomputed}`,
+    };
+  }
+
+  private checkEntryHashConsistency(cert: CertificatePayload): VerificationCheck {
+    // Extract output_hash from each canonical entry and compare with entry_hashes
+    const canonicalHashes: string[] = [];
+    for (const canonical of cert.integrity.canonical_entries) {
+      try {
+        const parsed = JSON.parse(canonical) as { output_hash: string };
+        canonicalHashes.push(parsed.output_hash);
+      } catch {
+        return {
+          name: 'entry_hash_consistency',
+          passed: false,
+          detail: 'Failed to parse canonical entry — data may be corrupted',
+        };
+      }
+    }
+
+    // Compare with entry_hashes array
+    if (canonicalHashes.length !== cert.integrity.entry_hashes.length) {
+      return {
+        name: 'entry_hash_consistency',
+        passed: false,
+        detail: `Entry count mismatch: ${canonicalHashes.length} canonical entries vs ${cert.integrity.entry_hashes.length} entry_hashes`,
+      };
+    }
+
+    for (let i = 0; i < canonicalHashes.length; i++) {
+      if (canonicalHashes[i] !== cert.integrity.entry_hashes[i]) {
+        return {
+          name: 'entry_hash_consistency',
+          passed: false,
+          detail: `Entry hash mismatch at index ${i}: canonical has ${canonicalHashes[i]}, entry_hashes has ${cert.integrity.entry_hashes[i]}`,
+        };
+      }
+    }
+
+    return {
+      name: 'entry_hash_consistency',
+      passed: true,
+      detail: `All ${canonicalHashes.length} entry hashes are consistent between canonical entries and entry_hashes array`,
+    };
+  }
+}