secaudit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Ouyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# secaudit — Deterministic 10-K Filing Analyzer
+
+A TypeScript CLI that demonstrates the difference between **command-driven (deterministic)** and **intent-based (probabilistic)** invocation using public SEC 10-K filings.
+
+**Core thesis:** Intent-based invocation is probabilistic; command-driven invocation is deterministic and auditable.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev -- analyze-10k --ticker AAPL --year 2023 --mode command
+```
+
+Output lands in `./out/`:
+- `{invocationId}-analysis.json` — structured section analysis
+- `{invocationId}-ledger.json` — audit ledger proving which steps ran
+
+## Two Invocation Modes
+
+### Command Mode (Deterministic)
+
+Every required step must pass. Missing sections = hard failure (exit code 2). The audit ledger proves 100% step coverage.
+
+```bash
+# Deterministic analysis — fails loudly if anything is missing
+npm run dev -- analyze-10k --ticker AAPL --year 2023 --mode command
+
+# Markdown output
+npm run dev -- analyze-10k --ticker TSLA --year 2023 --mode command --format md
+
+# Direct URL override
+npm run dev -- analyze-10k --ticker MSFT --year 2023 --source url \
+  --url "https://www.sec.gov/Archives/edgar/data/..." --mode command
+```
+
+### Intent Mode (Probabilistic)
+
+The system interprets natural language. Required steps may be skipped — the ledger exposes this gap.
+
+```bash
+# Intent-based — may skip validation
+npm run dev -- intent "analyze apple 10-k for 2023 and summarize risks"
+
+# Override ticker/year if intent parsing misses
+npm run dev -- intent "summarize tesla financial risks" --ticker TSLA --year 2023
+```
+
+## CLI Reference
+
+```
+secaudit analyze-10k [options]     Deterministic workflow
+secaudit intent <text> [options]   Probabilistic intent routing
+
+Options (analyze-10k):
+  --ticker <string>         Company ticker (e.g., AAPL, TSLA, MSFT)
+  --year <number>           Filing year
+  --mode <command|intent>   Invocation mode (default: command)
+  --format <json|md>        Output format (default: json)
+  --out <path>              Output directory (default: ./out)
+  --source <sec|url>        Fetch source (default: sec)
+  --url <string>            Direct filing URL
+  --require <list>          Required sections (default: risk-factors,mdna,financials)
+  --no-strict               Lower confidence thresholds
+  --no-cache                Skip document cache
+  --invocation-id <string>  Explicit invocation ID
+```
+
+## Workflow: `analyze_10k_v1`
+
+Six steps, executed in order:
+
+| Step | Description | Command Mode | Intent Mode |
+|------|-------------|-------------|-------------|
+| fetch | Download filing from SEC EDGAR | Required | Required |
+| extract | Parse HTML/PDF to text | Required | Required |
+| locate_sections | Find Item 1A, 7, 8 headings | Required | May skip |
+| validate | Check section presence & confidence | Required (hard fail) | May skip |
+| generate | Extractive summarization | Required | Best-effort |
+| emit_ledger | Write audit record | Always | Always |
+
+## Audit Ledger
+
+Every run produces a ledger showing exactly what happened:
+
+```json
+{
+  "mode": "command",
+  "deterministic": true,
+  "requiredSteps": ["fetch", "extract", "locate_sections", "validate", "generate", "emit_ledger"],
+  "executedSteps": ["fetch", "extract", "locate_sections", "validate", "generate", "emit_ledger"],
+  "skippedSteps": [],
+  "sectionValidation": {
+    "risk_factors": { "found": true, "confidence": 0.95, "lengthChars": 68735 },
+    "mdna": { "found": true, "confidence": 0.90, "lengthChars": 15092 },
+    "financials": { "found": true, "confidence": 0.95, "lengthChars": 19148 }
+  },
+  "passed": true
+}
+```
+
+In intent mode, you'll see `"deterministic": false` and potentially `"skippedSteps": ["validate"]` — making the reliability gap visible.
+
+## Exit Codes
+
+- `0` — success
+- `1` — general error (network, parse failure)
+- `2` — validation failure (missing required sections, command mode only)
+
+## Architecture
+
+```
+src/
+  cli/commands.ts           Commander setup + flag parsing
+  control-plane/
+    orchestrator.ts         Workflow engine: step sequencing + enforcement
+    workflow.ts             Step definitions for analyze_10k_v1
+    types.ts                Core type definitions
+  intent-router/
+    router.ts               Keyword-based intent classifier
+    patterns.ts             Ticker/year extraction patterns
+  tools/
+    fetcher.ts              SEC EDGAR fetch + caching
+    extractor.ts            HTML (cheerio) + PDF (pdfjs-dist) extraction
+    cache.ts                File-based cache
+  analysis/
+    locator.ts              Section heading detection via DOM traversal
+    validator.ts            Section presence + confidence validation
+    summarizer.ts           Extractive keyword-scored summarization
+  ledger/
+    ledger.ts               Audit ledger builder
+    types.ts                Ledger schema
+  utils/
+    id.ts                   Invocation ID generation
+    timer.ts                Step timing
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck    # Type-check without emitting
+npm run build        # Build with tsup
+npm test             # Run tests
+```
+
+## Data Source
+
+Uses the [SEC EDGAR API](https://www.sec.gov/developer) to fetch public 10-K filings. All requests comply with SEC rate limits (<10 req/sec) and include a User-Agent header.
+
+Fetched documents are cached in `.cache/` for offline use.

package/dist/chunk-AXVYBLOA.js

@@ -0,0 +1,594 @@
+// src/tools/cache.ts
+import { createHash } from "crypto";
+import { mkdir, readFile, writeFile, stat } from "fs/promises";
+import { join } from "path";
+var CACHE_DIR = ".cache";
+function sanitize(key) {
+  return key.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function cacheKey(ticker, year, accession) {
+  if (accession) {
+    return `sec_${ticker}_${year}_${accession}`;
+  }
+  return `sec_${ticker}_${year}`;
+}
+function urlCacheKey(url) {
+  const hash = createHash("sha256").update(url).digest("hex").slice(0, 16);
+  return `url_${hash}`;
+}
+async function readCache(key) {
+  const path = join(CACHE_DIR, sanitize(key));
+  try {
+    await stat(path);
+    return await readFile(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function writeCache(key, content) {
+  await mkdir(CACHE_DIR, { recursive: true });
+  const path = join(CACHE_DIR, sanitize(key));
+  await writeFile(path, content, "utf-8");
+}
+
+// src/tools/fetcher.ts
+var SEC_USER_AGENT = "secaudit-cli simonouyang@yahoo.com";
+var SEC_RATE_LIMIT_MS = 120;
+var lastRequestTime = 0;
+async function throttle() {
+  const now = Date.now();
+  const elapsed = now - lastRequestTime;
+  if (elapsed < SEC_RATE_LIMIT_MS) {
+    await new Promise((r) => setTimeout(r, SEC_RATE_LIMIT_MS - elapsed));
+  }
+  lastRequestTime = Date.now();
+}
+async function secFetch(url) {
+  await throttle();
+  const res = await fetch(url, {
+    headers: { "User-Agent": SEC_USER_AGENT, Accept: "text/html,application/json" }
+  });
+  if (!res.ok) {
+    throw new Error(`SEC request failed: ${res.status} ${res.statusText} for ${url}`);
+  }
+  return res;
+}
+async function resolveCik(ticker) {
+  const res = await secFetch("https://www.sec.gov/files/company_tickers.json");
+  const data = await res.json();
+  for (const entry of Object.values(data)) {
+    if (entry.ticker.toUpperCase() === ticker.toUpperCase()) {
+      return String(entry.cik_str).padStart(10, "0");
+    }
+  }
+  throw new Error(`Ticker "${ticker}" not found in SEC company tickers`);
+}
+async function findFiling(cik, year) {
+  const url = `https://data.sec.gov/submissions/CIK${cik}.json`;
+  const res = await secFetch(url);
+  const data = await res.json();
+  const recent = data.filings.recent;
+  for (let i = 0; i < recent.form.length; i++) {
+    const form = recent.form[i];
+    if (form !== "10-K" && form !== "10-K/A") continue;
+    const filingDate = recent.filingDate[i];
+    const filingYear = parseInt(filingDate.slice(0, 4), 10);
+    if (filingYear === year || filingYear === year + 1) {
+      return {
+        accessionNumber: recent.accessionNumber[i],
+        primaryDocument: recent.primaryDocument[i],
+        filingDate
+      };
+    }
+  }
+  throw new Error(
+    `No 10-K filing found for CIK ${cik} around year ${year}. Try a different --year or use --source url with a direct URL.`
+  );
+}
+function buildDocUrl(cik, accession, primaryDoc) {
+  const accessionPath = accession.replace(/-/g, "");
+  return `https://www.sec.gov/Archives/edgar/data/${cik}/${accessionPath}/${primaryDoc}`;
+}
+function detectContentType(content, url) {
+  if (url.endsWith(".pdf") || content.startsWith("%PDF")) return "pdf";
+  if (content.includes("<html") || content.includes("<HTML") || content.includes("<DOCUMENT>")) {
+    return "html";
+  }
+  return "text";
+}
+async function fetchFiling(options) {
+  if (options.url) {
+    return fetchByUrl(options.url, options.cache);
+  }
+  return fetchFromEdgar(options.ticker, options.year, options.cache);
+}
+async function fetchByUrl(url, useCache) {
+  const key = urlCacheKey(url);
+  if (useCache) {
+    const cached = await readCache(key);
+    if (cached) {
+      console.log("    (cache hit)");
+      return { content: cached, contentType: detectContentType(cached, url) };
+    }
+  }
+  const res = await secFetch(url);
+  const content = await res.text();
+  if (useCache) {
+    await writeCache(key, content);
+  }
+  return { content, contentType: detectContentType(content, url) };
+}
+async function fetchFromEdgar(ticker, year, useCache) {
+  const cik = await resolveCik(ticker);
+  console.log(`    CIK: ${cik}`);
+  const filing = await findFiling(cik, year);
+  console.log(`    Filing: ${filing.accessionNumber} (${filing.filingDate})`);
+  const key = cacheKey(ticker, year, filing.accessionNumber);
+  if (useCache) {
+    const cached = await readCache(key);
+    if (cached) {
+      console.log("    (cache hit)");
+      return { content: cached, contentType: detectContentType(cached, "") };
+    }
+  }
+  const docUrl = buildDocUrl(cik, filing.accessionNumber, filing.primaryDocument);
+  console.log(`    URL: ${docUrl}`);
+  const res = await secFetch(docUrl);
+  const content = await res.text();
+  if (useCache) {
+    await writeCache(key, content);
+  }
+  return { content, contentType: detectContentType(content, docUrl) };
+}
+
+// src/tools/extractor.ts
+import * as cheerio from "cheerio";
+async function extractText(rawContent, contentType) {
+  switch (contentType) {
+    case "html":
+      return extractFromHtml(rawContent);
+    case "pdf":
+      return extractFromPdf(rawContent);
+    case "text":
+      return rawContent;
+  }
+}
+function extractFromHtml(html) {
+  const $ = cheerio.load(html);
+  $("script, style, noscript, meta, link").remove();
+  const blocks = [];
+  const seen = /* @__PURE__ */ new Set();
+  $("p, td, th, li, h1, h2, h3, h4, h5, h6, dt, dd, blockquote").each((_, el) => {
+    const text = $(el).contents().toArray().map((n) => $(n).text()).join(" ").replace(/\s+/g, " ").trim();
+    if (text.length > 2 && !seen.has(text)) {
+      seen.add(text);
+      blocks.push(text);
+    }
+  });
+  if (blocks.length === 0) {
+    const body = $("body").text().replace(/\s+/g, " ").trim();
+    if (body.length > 0) return body;
+    return $.text().replace(/\s+/g, " ").trim();
+  }
+  return blocks.join("\n");
+}
+async function extractFromPdf(content) {
+  try {
+    const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+    const data = new Uint8Array(Buffer.from(content, "binary"));
+    const doc = await pdfjs.getDocument({ data }).promise;
+    const pages = [];
+    for (let i = 1; i <= doc.numPages; i++) {
+      const page = await doc.getPage(i);
+      const textContent = await page.getTextContent();
+      const pageText = textContent.items.filter((item) => "str" in item).map((item) => item.str).join(" ");
+      pages.push(pageText);
+    }
+    return pages.join("\n\n");
+  } catch (err) {
+    throw new Error(
+      `PDF extraction failed: ${err instanceof Error ? err.message : String(err)}. Try providing an HTML filing URL instead.`
+    );
+  }
+}
+
+// src/analysis/locator.ts
+import * as cheerio2 from "cheerio";
+var SECTION_PATTERNS = [
+  {
+    key: "risk_factors",
+    requireKeys: ["risk-factors", "risk_factors"],
+    headingPatterns: [
+      /^item\s+1a[\.\s\-—–]+risk\s+factors/i,
+      /^item\s+1a\b/i
+    ]
+  },
+  {
+    key: "mdna",
+    requireKeys: ["mdna", "md&a", "mda"],
+    headingPatterns: [
+      /^item\s+7[\.\s\-—–]+management'?s?\s+discussion/i,
+      /^item\s+7\b(?!\s*a)/i
+    ]
+  },
+  {
+    key: "financials",
+    requireKeys: ["financials", "financial-statements", "financial_statements"],
+    headingPatterns: [
+      /^item\s+8[\.\s\-—–]+financial\s+statements/i,
+      /^item\s+8\b/i
+    ]
+  }
+];
+var NEXT_ITEM_HEADING = /^item\s+\d+[a-z]?[\.\s\-—–]/i;
+function locateSections(rawHtml, extractedText, contentType) {
+  if (contentType === "html") {
+    return locateInHtml(rawHtml);
+  }
+  return locateInText(extractedText);
+}
+function locateInHtml(html) {
+  const $ = cheerio2.load(html);
+  const results = [];
+  const bodyDivs = $("body > div").toArray();
+  for (const pattern of SECTION_PATTERNS) {
+    const match = findSectionByDomSiblings($, bodyDivs, pattern);
+    results.push(match);
+  }
+  return results;
+}
+function findSectionByDomSiblings($, bodyDivs, pattern) {
+  let headingIdx = -1;
+  let confidence = 0;
+  for (let i = 0; i < bodyDivs.length; i++) {
+    const text = $(bodyDivs[i]).text().replace(/\s+/g, " ").trim();
+    if (text.length > 150 || text.length < 3) continue;
+    for (let pi = 0; pi < pattern.headingPatterns.length; pi++) {
+      if (pattern.headingPatterns[pi].test(text)) {
+        headingIdx = i;
+        confidence = pi === 0 ? 0.95 : 0.9;
+        break;
+      }
+    }
+    if (headingIdx >= 0) break;
+  }
+  if (headingIdx < 0) {
+    return makeNotFound(pattern.key);
+  }
+  const contentBlocks = [];
+  let endIdx = bodyDivs.length;
+  for (let i = headingIdx + 1; i < bodyDivs.length; i++) {
+    const text = $(bodyDivs[i]).text().replace(/\s+/g, " ").trim();
+    if (text.length < 100 && NEXT_ITEM_HEADING.test(text)) {
+      endIdx = i;
+      break;
+    }
+    if (text.length > 2) {
+      contentBlocks.push(text);
+    }
+  }
+  const content = contentBlocks.join("\n");
+  return {
+    name: pattern.key,
+    found: true,
+    confidence,
+    startOffset: headingIdx,
+    endOffset: endIdx,
+    lengthChars: content.length,
+    content
+  };
+}
+function locateInText(text) {
+  const allPatterns = [
+    ...SECTION_PATTERNS.map((p) => ({
+      ...p,
+      headingPatterns: p.headingPatterns.map(
+        (r) => new RegExp(r.source.replace(/^\^/, ""), r.flags)
+      )
+    }))
+  ];
+  return allPatterns.map((pattern) => {
+    for (let pi = 0; pi < pattern.headingPatterns.length; pi++) {
+      const match = pattern.headingPatterns[pi].exec(text);
+      if (match) {
+        const confidence = pi === 0 ? 0.9 : 0.85;
+        const startOffset = match.index;
+        const sectionContent = extractTextSection(text, startOffset);
+        return {
+          name: pattern.key,
+          found: true,
+          confidence,
+          startOffset,
+          endOffset: startOffset + sectionContent.length,
+          lengthChars: sectionContent.length,
+          content: sectionContent
+        };
+      }
+    }
+    return makeNotFound(pattern.key);
+  });
+}
+function extractTextSection(text, startOffset) {
+  const afterHeading = text.slice(startOffset);
+  const lines = afterHeading.split("\n");
+  let endIdx = -1;
+  for (let i = 3; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.length < 3) continue;
+    if (NEXT_ITEM_HEADING.test(trimmed) && trimmed.length < 150) {
+      endIdx = i;
+      break;
+    }
+  }
+  const sectionLines = endIdx > 0 ? lines.slice(0, endIdx) : lines.slice(0, 800);
+  const content = sectionLines.join("\n").trim();
+  if (content.length > 1e5) {
+    return content.slice(0, 1e5);
+  }
+  return content;
+}
+function makeNotFound(name) {
+  return {
+    name,
+    found: false,
+    confidence: 0,
+    startOffset: -1,
+    endOffset: -1,
+    lengthChars: 0,
+    content: ""
+  };
+}
+function matchesSectionKey(sectionName, requireKey) {
+  const pattern = SECTION_PATTERNS.find((p) => p.key === sectionName);
+  if (!pattern) return false;
+  return pattern.requireKeys.includes(requireKey.toLowerCase());
+}
+
+// src/analysis/validator.ts
+var MIN_SECTION_LENGTH = 500;
+function validateSections(sections, requiredKeys, confidenceThreshold, hardFail) {
+  const failures = [];
+  for (const reqKey of requiredKeys) {
+    const section = sections.find((s) => matchesSectionKey(s.name, reqKey));
+    if (!section || !section.found) {
+      failures.push(`Section "${reqKey}" not found in filing`);
+      continue;
+    }
+    if (section.confidence < confidenceThreshold) {
+      failures.push(
+        `Section "${reqKey}" confidence ${section.confidence.toFixed(2)} below threshold ${confidenceThreshold.toFixed(2)}`
+      );
+    }
+    if (section.lengthChars < MIN_SECTION_LENGTH) {
+      failures.push(
+        `Section "${reqKey}" too short (${section.lengthChars} chars, minimum ${MIN_SECTION_LENGTH})`
+      );
+    }
+  }
+  if (failures.length > 0) {
+    const message = `Validation failed:
+  - ${failures.join("\n  - ")}`;
+    if (hardFail) {
+      throw new Error(message);
+    }
+    console.warn(`  [warn] ${message}`);
+  }
+}
+
+// src/analysis/summarizer.ts
+var MAX_SUMMARY_POINTS = 5;
+var MAX_EVIDENCE_SNIPPETS = 3;
+var SENTENCE_END = /(?<=[.!?])\s+/;
+var RISK_KEYWORDS = [
+  "risk",
+  "adverse",
+  "uncertainty",
+  "litigation",
+  "regulatory",
+  "competition",
+  "cybersecurity",
+  "supply chain",
+  "economic",
+  "volatility",
+  "liability",
+  "compliance",
+  "disruption"
+];
+var FINANCIAL_KEYWORDS = [
+  "revenue",
+  "income",
+  "loss",
+  "margin",
+  "earnings",
+  "cash flow",
+  "assets",
+  "liabilities",
+  "debt",
+  "capital",
+  "dividend",
+  "operating",
+  "growth",
+  "decline",
+  "increase",
+  "decrease"
+];
+var MDNA_KEYWORDS = [
+  "revenue",
+  "growth",
+  "margin",
+  "decline",
+  "increase",
+  "segment",
+  "operating",
+  "strategy",
+  "outlook",
+  "trend",
+  "driver",
+  "year-over-year",
+  "compared to",
+  "primarily due",
+  "result of"
+];
+function generateAnalysis(sections, requiredKeys) {
+  const analyses = [];
+  for (const reqKey of requiredKeys) {
+    const section = sections.find((s) => matchesSectionKey(s.name, reqKey));
+    if (!section || !section.found) {
+      analyses.push({
+        name: sectionKeyToName(reqKey),
+        found: false,
+        confidence: 0,
+        summary: [],
+        evidence: []
+      });
+      continue;
+    }
+    const keywords = getKeywordsForSection(section.name);
+    const sentences = splitSentences(section.content);
+    const scored = scoreSentences(sentences, keywords);
+    analyses.push({
+      name: section.name,
+      found: true,
+      confidence: section.confidence,
+      summary: scored.slice(0, MAX_SUMMARY_POINTS).map((s) => s.text),
+      evidence: scored.slice(0, MAX_EVIDENCE_SNIPPETS).map((s) => truncate(s.text, 200))
+    });
+  }
+  const overallSummary = buildOverallSummary(analyses);
+  return { sections: analyses, overallSummary };
+}
+function scoreSentences(sentences, keywords) {
+  const scored = sentences.filter((s) => s.length > 30 && s.length < 500).map((text) => {
+    const lower = text.toLowerCase();
+    let score = 0;
+    for (const kw of keywords) {
+      if (lower.includes(kw.toLowerCase())) {
+        score += 1;
+      }
+    }
+    if (/\$[\d,.]+/.test(text) || /\d+(\.\d+)?%/.test(text)) {
+      score += 0.5;
+    }
+    return { text, score };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  return scored;
+}
+function splitSentences(text) {
+  return text.split(SENTENCE_END).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function getKeywordsForSection(name) {
+  switch (name) {
+    case "risk_factors":
+      return RISK_KEYWORDS;
+    case "mdna":
+      return MDNA_KEYWORDS;
+    case "financials":
+      return FINANCIAL_KEYWORDS;
+    default:
+      return [...RISK_KEYWORDS, ...FINANCIAL_KEYWORDS];
+  }
+}
+function sectionKeyToName(key) {
+  const map = {
+    "risk-factors": "risk_factors",
+    "risk_factors": "risk_factors",
+    "mdna": "mdna",
+    "md&a": "mdna",
+    "mda": "mdna",
+    "financials": "financials",
+    "financial-statements": "financials",
+    "financial_statements": "financials"
+  };
+  return map[key.toLowerCase()] ?? key;
+}
+function truncate(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + "...";
+}
+function buildOverallSummary(analyses) {
+  const summary = [];
+  const found = analyses.filter((a) => a.found);
+  const missing = analyses.filter((a) => !a.found);
+  if (found.length > 0) {
+    summary.push(
+      `Analyzed ${found.length} section(s): ${found.map((a) => a.name).join(", ")}.`
+    );
+  }
+  if (missing.length > 0) {
+    summary.push(
+      `Missing section(s): ${missing.map((a) => a.name).join(", ")}.`
+    );
+  }
+  for (const a of found) {
+    if (a.summary.length > 0) {
+      summary.push(`${a.name}: ${a.summary[0]}`);
+    }
+  }
+  return summary;
+}
+
+// src/control-plane/workflow.ts
+var COMMAND_CONFIDENCE_THRESHOLD = 0.75;
+var INTENT_CONFIDENCE_THRESHOLD = 0.5;
+function buildWorkflow(options) {
+  const isCommand = options.mode === "command";
+  const threshold = isCommand ? COMMAND_CONFIDENCE_THRESHOLD : INTENT_CONFIDENCE_THRESHOLD;
+  const steps = [
+    {
+      name: "fetch",
+      required: true,
+      execute: async (ctx) => {
+        const result = await fetchFiling(ctx.options);
+        ctx.rawContent = result.content;
+        ctx.contentType = result.contentType;
+      }
+    },
+    {
+      name: "extract",
+      required: true,
+      execute: async (ctx) => {
+        ctx.extractedText = await extractText(ctx.rawContent, ctx.contentType);
+        if (ctx.extractedText.length < 1e3) {
+          throw new Error(
+            `Extracted text too short (${ctx.extractedText.length} chars). Filing may be malformed.`
+          );
+        }
+      }
+    },
+    {
+      name: "locate_sections",
+      required: true,
+      execute: async (ctx) => {
+        ctx.sections = locateSections(ctx.rawContent, ctx.extractedText, ctx.contentType);
+      }
+    },
+    {
+      name: "validate",
+      required: isCommand,
+      execute: async (ctx) => {
+        validateSections(ctx.sections, ctx.options.require, threshold, isCommand);
+      }
+    },
+    {
+      name: "generate",
+      required: isCommand,
+      execute: async (ctx) => {
+        const result = generateAnalysis(ctx.sections, ctx.options.require);
+        ctx.analyses = result.sections;
+        ctx.overallSummary = result.overallSummary;
+      }
+    },
+    {
+      name: "emit_ledger",
+      required: true,
+      execute: async () => {
+      }
+    }
+  ];
+  return { steps, skippedSteps: [], confidenceThreshold: threshold };
+}
+
+export {
+  buildWorkflow
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+import {
+  buildWorkflow
+} from "./chunk-AXVYBLOA.js";
+
+// src/index.ts
+import "dotenv/config";
+
+// src/cli/commands.ts
+import { Command } from "commander";
+
+// src/utils/id.ts
+import { randomBytes } from "crypto";
+function generateInvocationId() {
+  const now = /* @__PURE__ */ new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const rand = randomBytes(3).toString("hex");
+  return `inv_${date}_${rand}`;
+}
+
+// src/control-plane/orchestrator.ts
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+// src/utils/timer.ts
+var StepTimer = class {
+  start = 0n;
+  begin() {
+    this.start = process.hrtime.bigint();
+  }
+  elapsed() {
+    const end = process.hrtime.bigint();
+    return Number((end - this.start) / 1000000n);
+  }
+};
+
+// src/ledger/ledger.ts
+var ALL_REQUIRED_STEPS = [
+  "fetch",
+  "extract",
+  "locate_sections",
+  "validate",
+  "generate",
+  "emit_ledger"
+];
+function buildLedger(ctx, plan, passed, failureReason) {
+  const durationsMs = {};
+  const executedSteps = [];
+  const skippedSteps = [...plan.skippedSteps];
+  for (const result of ctx.stepResults) {
+    durationsMs[result.name] = result.durationMs;
+    if (result.status === "passed" || result.status === "failed") {
+      executedSteps.push(result.name);
+    } else if (result.status === "skipped" && !skippedSteps.includes(result.name)) {
+      skippedSteps.push(result.name);
+    }
+  }
+  const sectionValidation = {};
+  for (const section of ctx.sections) {
+    sectionValidation[section.name] = {
+      found: section.found,
+      confidence: section.confidence,
+      lengthChars: section.lengthChars
+    };
+  }
+  return {
+    invocationId: ctx.options.invocationId,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    mode: ctx.options.mode,
+    deterministic: ctx.options.mode === "command",
+    workflow: "analyze_10k_v1",
+    requiredSteps: ALL_REQUIRED_STEPS,
+    executedSteps,
+    skippedSteps,
+    durationsMs,
+    sectionValidation,
+    passed,
+    failureReason
+  };
+}
+
+// src/control-plane/orchestrator.ts
+async function runWorkflow(options, intentPlan) {
+  const ctx = {
+    options,
+    rawContent: "",
+    contentType: "html",
+    extractedText: "",
+    sections: [],
+    analyses: [],
+    stepResults: [],
+    overallSummary: []
+  };
+  const plan = intentPlan ?? buildWorkflow(options);
+  const skippedSet = new Set(plan.skippedSteps);
+  const timer = new StepTimer();
+  console.log(
+    `
+[secaudit] mode=${options.mode} workflow=analyze_10k_v1 id=${options.invocationId}`
+  );
+  console.log(
+    `[secaudit] ticker=${options.ticker} year=${options.year} strict=${options.strict}
+`
+  );
+  for (const step of plan.steps) {
+    if (skippedSet.has(step.name)) {
+      ctx.stepResults.push({
+        name: step.name,
+        status: "skipped",
+        durationMs: 0
+      });
+      console.log(`  [skip] ${step.name}`);
+      continue;
+    }
+    timer.begin();
+    console.log(`  [run]  ${step.name}...`);
+    try {
+      await step.execute(ctx);
+      const duration = timer.elapsed();
+      ctx.stepResults.push({
+        name: step.name,
+        status: "passed",
+        durationMs: duration
+      });
+      console.log(`  [pass] ${step.name} (${duration}ms)`);
+    } catch (err) {
+      const duration = timer.elapsed();
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.stepResults.push({
+        name: step.name,
+        status: "failed",
+        durationMs: duration,
+        error: message
+      });
+      console.error(`  [FAIL] ${step.name}: ${message}`);
+      if (options.mode === "command" && step.required) {
+        await emitOutputs(ctx, plan, false, message);
+        console.error(
+          `
+[secaudit] FATAL: required step "${step.name}" failed in command mode`
+        );
+        printRemediation(step.name, message);
+        process.exit(2);
+      }
+    }
+  }
+  await emitOutputs(ctx, plan, true);
+  console.log(`
+[secaudit] done. Output written to ${options.out}/`);
+}
+async function emitOutputs(ctx, plan, passed, failureReason) {
+  const { options } = ctx;
+  await mkdir(options.out, { recursive: true });
+  const ledger = buildLedger(ctx, plan, passed, failureReason);
+  const ledgerPath = join(options.out, `${options.invocationId}-ledger.json`);
+  await writeFile(ledgerPath, JSON.stringify(ledger, null, 2));
+  if (passed) {
+    const analysis = buildAnalysisOutput(ctx);
+    const ext = options.format === "md" ? "md" : "json";
+    const analysisPath = join(options.out, `${options.invocationId}-analysis.${ext}`);
+    if (options.format === "md") {
+      await writeFile(analysisPath, renderMarkdown(analysis));
+    } else {
+      await writeFile(analysisPath, JSON.stringify(analysis, null, 2));
+    }
+  }
+}
+function buildAnalysisOutput(ctx) {
+  return {
+    invocationId: ctx.options.invocationId,
+    mode: ctx.options.mode,
+    workflow: "analyze_10k_v1",
+    input: { ticker: ctx.options.ticker, year: ctx.options.year },
+    sections: ctx.analyses,
+    overallSummary: ctx.overallSummary
+  };
+}
+function renderMarkdown(analysis) {
+  const lines = [
+    `# 10-K Analysis: ${analysis.input.ticker} (${analysis.input.year})`,
+    "",
+    `**Mode:** ${analysis.mode}`,
+    `**Workflow:** ${analysis.workflow}`,
+    `**Invocation ID:** ${analysis.invocationId}`,
+    ""
+  ];
+  for (const section of analysis.sections) {
+    lines.push(`## ${formatSectionName(section.name)}`);
+    lines.push("");
+    lines.push(`**Found:** ${section.found} | **Confidence:** ${section.confidence}`);
+    lines.push("");
+    if (section.summary.length > 0) {
+      lines.push("### Summary");
+      for (const s of section.summary) {
+        lines.push(`- ${s}`);
+      }
+      lines.push("");
+    }
+    if (section.evidence.length > 0) {
+      lines.push("### Evidence");
+      for (const e of section.evidence) {
+        lines.push(`> ${e}`);
+      }
+      lines.push("");
+    }
+  }
+  if (analysis.overallSummary.length > 0) {
+    lines.push("## Overall Summary");
+    lines.push("");
+    for (const s of analysis.overallSummary) {
+      lines.push(`- ${s}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatSectionName(name) {
+  const map = {
+    risk_factors: "Risk Factors (Item 1A)",
+    mdna: "Management's Discussion & Analysis (Item 7)",
+    financials: "Financial Statements (Item 8)"
+  };
+  return map[name] ?? name;
+}
+function printRemediation(stepName, error) {
+  console.error("\n[secaudit] Remediation suggestions:");
+  if (stepName === "fetch") {
+    console.error("  - Try --source url --url <direct-filing-url>");
+    console.error("  - Check ticker spelling and year availability");
+  } else if (stepName === "extract") {
+    console.error("  - The filing format may be unsupported");
+    console.error("  - Try a different --source or provide --url to an HTML filing");
+  } else if (stepName === "validate") {
+    console.error("  - Try --no-strict to lower confidence thresholds");
+    console.error("  - Try a different filing year");
+    console.error(`  - Details: ${error}`);
+  }
+}
+
+// src/intent-router/patterns.ts
+var TICKER_PATTERNS = [
+  [/\bAAPL\b/i, "AAPL"],
+  [/\bapple\b/i, "AAPL"],
+  [/\bGOOG(?:L)?\b/i, "GOOGL"],
+  [/\bgoogle\b/i, "GOOGL"],
+  [/\balphabet\b/i, "GOOGL"],
+  [/\bMSFT\b/i, "MSFT"],
+  [/\bmicrosoft\b/i, "MSFT"],
+  [/\bAMZN\b/i, "AMZN"],
+  [/\bamazon\b/i, "AMZN"],
+  [/\bTSLA\b/i, "TSLA"],
+  [/\btesla\b/i, "TSLA"],
+  [/\bMETA\b/i, "META"],
+  [/\bmeta\b/i, "META"],
+  [/\bfacebook\b/i, "META"],
+  [/\bNVDA\b/i, "NVDA"],
+  [/\bnvidia\b/i, "NVDA"]
+];
+var GENERIC_TICKER = /\b([A-Z]{1,5})\b/;
+function extractTicker(text) {
+  for (const [pattern, ticker] of TICKER_PATTERNS) {
+    if (pattern.test(text)) return ticker;
+  }
+  const match = GENERIC_TICKER.exec(text);
+  if (match) {
+    const candidate = match[1];
+    const stopWords = /* @__PURE__ */ new Set([
+      "THE",
+      "AND",
+      "FOR",
+      "ARE",
+      "BUT",
+      "NOT",
+      "YOU",
+      "ALL",
+      "CAN",
+      "HER",
+      "WAS",
+      "ONE",
+      "OUR",
+      "OUT",
+      "SEC",
+      "PDF"
+    ]);
+    if (!stopWords.has(candidate) && candidate.length >= 2) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function extractYear(text) {
+  const yearPattern = /\b(20[1-3]\d)\b/g;
+  let match;
+  const years = [];
+  while ((match = yearPattern.exec(text)) !== null) {
+    years.push(parseInt(match[1], 10));
+  }
+  if (years.length === 0) return null;
+  years.sort((a, b) => b - a);
+  return years[0];
+}
+function extractIntentSignals(text) {
+  const lower = text.toLowerCase();
+  return {
+    wantsRiskFactors: lower.includes("risk") || lower.includes("item 1a"),
+    wantsMdna: lower.includes("md&a") || lower.includes("discussion") || lower.includes("management") || lower.includes("item 7"),
+    wantsFinancials: lower.includes("financial") || lower.includes("revenue") || lower.includes("earnings") || lower.includes("item 8") || lower.includes("balance sheet"),
+    isVague: !lower.includes("risk") && !lower.includes("financial") && !lower.includes("md&a") && !lower.includes("discussion") && !lower.includes("item")
+  };
+}
+
+// src/intent-router/router.ts
+function routeIntent(text, overrides) {
+  const ticker = overrides.ticker ?? extractTicker(text);
+  const year = overrides.year ?? extractYear(text);
+  if (!ticker) {
+    throw new Error(
+      'Could not determine ticker from intent. Try: secaudit intent "analyze AAPL 10-K 2023", or provide --ticker explicitly.'
+    );
+  }
+  if (!year) {
+    throw new Error(
+      'Could not determine year from intent. Try including a year like "2023" or provide --year explicitly.'
+    );
+  }
+  const signals = extractIntentSignals(text);
+  const requiredSections = resolveRequiredSections(signals);
+  const stubOptions = {
+    ticker,
+    year,
+    mode: "intent",
+    format: "json",
+    out: "./out",
+    source: "sec",
+    require: requiredSections,
+    strict: false,
+    cache: true,
+    invocationId: ""
+  };
+  const plan = buildWorkflow(stubOptions);
+  const skipped = computeProbabilisticSkips(signals);
+  plan.skippedSteps = skipped;
+  console.log(`  [intent] Router: heuristic (keyword-based)`);
+  console.log(`  [intent] Resolved: ticker=${ticker} year=${year}`);
+  console.log(`  [intent] Sections: ${requiredSections.join(", ")}`);
+  if (skipped.length > 0) {
+    console.log(`  [intent] Probabilistic skips: ${skipped.join(", ")}`);
+  }
+  return { ticker, year, requiredSections, plan };
+}
+function resolveRequiredSections(signals) {
+  if (signals.isVague) {
+    return ["risk-factors", "mdna", "financials"];
+  }
+  const sections = [];
+  if (signals.wantsRiskFactors) sections.push("risk-factors");
+  if (signals.wantsMdna) sections.push("mdna");
+  if (signals.wantsFinancials) sections.push("financials");
+  return sections.length > 0 ? sections : ["risk-factors", "mdna", "financials"];
+}
+function computeProbabilisticSkips(signals) {
+  const skips = [];
+  if (Math.random() < 0.5) {
+    skips.push("validate");
+  }
+  if (signals.isVague && Math.random() < 0.4) {
+    skips.push("locate_sections");
+  }
+  if (Math.random() < 0.2) {
+    skips.push("generate");
+  }
+  return skips;
+}
+
+// src/cli/commands.ts
+var DEFAULT_REQUIRE = ["risk-factors", "mdna", "financials"];
+function buildCli() {
+  const program2 = new Command();
+  program2.name("secaudit").description(
+    "Deterministic 10-K filing analyzer.\n\nDemonstrates command-driven (deterministic) vs intent-based (probabilistic) invocation.\nProcesses public SEC 10-K filings and produces structured analysis with an audit ledger."
+  ).version("0.1.0");
+  program2.command("analyze-10k").description("Analyze a 10-K filing with full workflow enforcement").requiredOption("--ticker <string>", "Company ticker symbol (e.g., AAPL)").requiredOption("--year <number>", "Filing year", parseInt).option("--mode <mode>", "Invocation mode: command or intent", "command").option("--format <format>", "Output format: json or md", "json").option("--out <path>", "Output directory", "./out").option("--source <source>", "Fetch source: sec, edgar-archive, or url", "sec").option("--url <string>", "Direct filing URL (overrides ticker/year lookup)").option("--require <list>", "Required sections (comma-separated)", DEFAULT_REQUIRE.join(",")).option("--no-strict", "Disable strict parsing thresholds").option("--no-cache", "Disable document caching").option("--invocation-id <string>", "Explicit invocation ID").action(async (opts) => {
+    const options = {
+      ticker: opts.ticker.toUpperCase(),
+      year: opts.year,
+      mode: opts.mode,
+      format: opts.format,
+      out: opts.out,
+      source: opts.source,
+      url: opts.url,
+      require: opts.require.split(",").map((s) => s.trim()),
+      strict: opts.strict !== false,
+      cache: opts.cache !== false,
+      invocationId: opts.invocationId || generateInvocationId()
+    };
+    await runWorkflow(options);
+  });
+  program2.command("intent").description("Analyze a filing via natural language intent (probabilistic mode)").argument("<text>", 'Natural language request (e.g., "analyze apple 10-k 2023 risks")').option("--llm", "Use OpenAI GPT to route intent (requires OPENAI_API_KEY)").option("--model <model>", "OpenAI model to use with --llm (default: gpt-4o-mini)", "gpt-4o-mini").option("--format <format>", "Output format: json or md", "json").option("--out <path>", "Output directory", "./out").option("--ticker <string>", "Optional ticker override").option("--year <number>", "Optional year override", parseInt).option("--no-cache", "Disable document caching").option("--invocation-id <string>", "Explicit invocation ID").action(async (text, opts) => {
+    const overrides = {
+      ticker: opts.ticker?.toUpperCase(),
+      year: opts.year
+    };
+    let resolved;
+    if (opts.llm) {
+      const { routeIntentWithLlm } = await import("./llm-router-JZRXUHBF.js");
+      resolved = await routeIntentWithLlm(text, overrides, opts.model);
+    } else {
+      resolved = routeIntent(text, overrides);
+    }
+    const options = {
+      ticker: resolved.ticker,
+      year: resolved.year,
+      mode: "intent",
+      format: opts.format,
+      out: opts.out,
+      source: "sec",
+      require: resolved.requiredSections,
+      strict: false,
+      cache: opts.cache !== false,
+      invocationId: opts.invocationId || generateInvocationId()
+    };
+    await runWorkflow(options, resolved.plan);
+  });
+  return program2;
+}
+
+// src/index.ts
+var program = buildCli();
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`secaudit: ${err.message}`);
+  process.exit(1);
+});

package/dist/llm-router-JZRXUHBF.js

@@ -0,0 +1,103 @@
+import {
+  buildWorkflow
+} from "./chunk-AXVYBLOA.js";
+
+// src/intent-router/llm-router.ts
+import OpenAI from "openai";
+var ALL_STEPS = [
+  "fetch",
+  "extract",
+  "locate_sections",
+  "validate",
+  "generate",
+  "emit_ledger"
+];
+var SYSTEM_PROMPT = `You are a workflow planner for a SEC 10-K filing analyzer.
+
+Given a user's natural language request, decide which workflow steps to execute.
+
+Available steps:
+- fetch: Download the 10-K filing from SEC EDGAR
+- extract: Parse the HTML/PDF document into text
+- locate_sections: Find required sections (Risk Factors, MD&A, Financial Statements)
+- validate: Verify that all required sections were found with sufficient confidence
+- generate: Produce extractive summaries for each section
+- emit_ledger: Write an audit record of what ran
+
+Respond with ONLY a JSON object in this exact format:
+{
+  "ticker": "AAPL",
+  "year": 2023,
+  "steps": ["fetch", "extract", ...],
+  "sections": ["risk-factors", "mdna", "financials"],
+  "reasoning": "brief explanation of your choices"
+}
+
+IMPORTANT: Only include steps you believe are necessary to fulfill the user's request.
+If the user only asks about risks, you may not need financials.
+If the request seems straightforward, you may skip validation.
+Use your judgment \u2014 include only what's needed.`;
+var DEFAULT_MODEL = "gpt-4o-mini";
+async function routeIntentWithLlm(text, overrides, model) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "OPENAI_API_KEY environment variable is required for --llm mode.\nSet it with: export OPENAI_API_KEY=sk-..."
+    );
+  }
+  const selectedModel = model ?? DEFAULT_MODEL;
+  const client = new OpenAI({ apiKey });
+  console.log(`  [llm] Sending intent to ${selectedModel}...`);
+  const response = await client.chat.completions.create({
+    model: selectedModel,
+    temperature: 0.7,
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: text }
+    ],
+    response_format: { type: "json_object" }
+  });
+  const raw = response.choices[0]?.message?.content;
+  if (!raw) {
+    throw new Error("LLM returned empty response");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`LLM returned invalid JSON: ${raw.slice(0, 200)}`);
+  }
+  const ticker = overrides.ticker ?? parsed.ticker;
+  const year = overrides.year ?? parsed.year;
+  if (!ticker) throw new Error("LLM could not determine ticker from intent");
+  if (!year) throw new Error("LLM could not determine year from intent");
+  const llmSteps = new Set(parsed.steps ?? []);
+  const skippedSteps = ALL_STEPS.filter((s) => !llmSteps.has(s));
+  const sections = parsed.sections?.length > 0 ? parsed.sections : ["risk-factors", "mdna", "financials"];
+  const stubOptions = {
+    ticker,
+    year,
+    mode: "intent",
+    format: "json",
+    out: "./out",
+    source: "sec",
+    require: sections,
+    strict: false,
+    cache: true,
+    invocationId: ""
+  };
+  const plan = buildWorkflow(stubOptions);
+  plan.skippedSteps = skippedSteps;
+  console.log(`  [llm] Model: ${selectedModel}`);
+  console.log(`  [llm] Resolved: ticker=${ticker} year=${year}`);
+  console.log(`  [llm] Steps chosen: ${parsed.steps?.join(", ") ?? "(none)"}`);
+  console.log(`  [llm] Sections: ${sections.join(", ")}`);
+  if (skippedSteps.length > 0) {
+    console.log(`  [llm] Skipped by LLM: ${skippedSteps.join(", ")}`);
+  }
+  console.log(`  [llm] Reasoning: ${parsed.reasoning}`);
+  return { ticker, year, requiredSections: sections, plan, reasoning: parsed.reasoning };
+}
+export {
+  routeIntentWithLlm
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "secaudit",
+  "version": "0.1.0",
+  "description": "Deterministic 10-K filing analyzer — command-driven vs intent-based invocation. Proves that intent-based invocation is probabilistic; command-driven invocation is deterministic and auditable.",
+  "type": "module",
+  "bin": {
+    "secaudit": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simonouyang/secaudit"
+  },
+  "author": "Simon Ouyang",
+  "license": "MIT",
+  "keywords": [
+    "sec",
+    "10-k",
+    "edgar",
+    "cli",
+    "deterministic",
+    "audit",
+    "intent",
+    "command-pattern",
+    "workflow",
+    "agent",
+    "llm"
+  ],
+  "dependencies": {
+    "cheerio": "^1.0.0",
+    "commander": "^12.1.0",
+    "dotenv": "^17.3.1",
+    "openai": "^6.22.0",
+    "pdfjs-dist": "^4.9.155"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}