wiki(dart-corr): reflect v0.7.1 — extracted to real package
Companion to agentic-dart commit 49e772c which extracts dart_corr
from a docs-only scaffold into a real standalone package with code,
14 unit tests, and an operator-tunable rule pack.
Wiki changes:
dart-corr.md
'Files' block — replaced the old tree (which showed a
nonexistent correlation-rules.yaml and pointed implementation
at dart_mcp) with the real v0.7.1 layout: pyproject.toml,
correlation-rules.yaml, src/dart_corr/__init__.py,
tests/test_dart_corr.py.
'Implementation note' — replaced the scaffold caveat with the
v0.7.1 reality: dart_corr is a real package, the MCP wire
surface is preserved through thin wrappers in dart_mcp, and
correlate_timeline keeps the SQL-injection defense at the
boundary.
Home.md
TOC entry for dart-corr — removed the '(implementation currently
inside dart_mcp; mid-2026 target)' subscript. The package is
real now.
Architecture-deep-dive.md
Package ownership table — removed the '*scaffold (v0.7.1) —
implementation lives in dart_mcp*' subscript on the dart_corr
row. dart_corr now genuinely owns what the table says it owns.
The agentic-dart README has been updated in lockstep with the
matching scaffold-removal language and the test count (79 → 93
total tests across both packages). All numbers and language now
reconcile across README, Wiki, and the dart_corr package itself.
fix(dart-corr): honest scaffold status across three Wiki pages
User flagged a real issue — dart_corr/ on github is a directory
containing only README.md, but multiple Wiki pages describe dart-corr
as if it were a functioning component with its own files. This commit
brings the Wiki language in line with the actual v0.7.1 source-tree
state.
Three changes:
(1) Wiki/dart-corr.md '## Files' section — the 'tree' diagram falsely
listed dart_corr/correlation-rules.yaml as a file that exists.
It does not exist in the repo. The Implementation note was
correct (it pointed at dart_mcp/__init__.py) but the file tree
contradicted it. Both replaced with an honest tree showing
only README.md under dart_corr/, plus exact line numbers for
the three real correlate_* functions inside dart_mcp.
(2) Wiki/Home.md Core-components TOC entry — added an inline
qualifier '(implementation currently inside dart_mcp; standalone
package is a mid-2026 target — see the page)' to the dart-corr
bullet, so a reader scanning the TOC does not click through
expecting a fully-populated package.
(3) Wiki/Architecture-deep-dive.md package-ownership table — added a
subscript '*scaffold (v0.7.1) — implementation lives in dart_mcp*'
to the dart_corr row, so the architectural diagram and the
ownership table tell the same truth.
What is NOT changed:
- The architectural design (dart-corr OWNS contradiction
detection as a logical responsibility) is correct and stays.
- The MCP-surface functions (correlate_events, correlate_timeline,
correlate_download_to_execution) are real, registered, and
reachable — verified by tests/test_mcp_surface.py.
- Case-PtH-Timestomp and Case-IP-KVM walkthroughs accurately
describe what those functions do; the 'dart-corr' references
in those pages are correct as descriptions of the logical
component, not as claims about file locations.
Why the discrepancy existed:
v0.4-era plan was to ship dart_corr/ as a standalone package
before the SANS submission. When the v0.5 timeline tightened,
the correlation logic was inlined into dart_mcp (where the
type system was already enforced) and the dart_corr/ extraction
was deferred to mid-2026. The main README, the agentic-dart
README, and dart_corr/README.md all updated honestly at that
time; some Wiki pages did not. Now they do.
wiki: naturalize hardcoded counts (Source of Truth lives in README Hero)
Following the same Single-Source-of-Truth cleanup applied to the main
repo: wiki pages no longer hardcode '67 typed functions / 42 native +
25 SIFT adapters / 10 of 12 MITRE / 55 tests / 1182 lines'. Phrasing
shifts to 'the typed MCP surface', 'native + SIFT adapters', 'broad
MITRE enterprise tactic coverage'.
Phase-1.md historical version table preserves period-specific numbers
(v0.3 = 31 functions, v0.4 = 35 native, v0.5 = 60 functions) because
those are historical facts about what shipped on those dates, not
claims about current state.
The canonical exact name set continues to live in
tests/test_mcp_surface.py — the only place that needs editing when a
function is added or removed.
wiki: sweep stale 35-native / 60-total counts to current 42 / 67
16 wiki pages had pre-v0.6.0 numeric references that survived earlier
QA rounds. Surface count was bumped 60 -> 67 in v0.6.0 (six new
supply-chain IOC functions in dart_mcp._v05_supply_chain), and native
count went 35 -> 42, but a number of wiki pages still showed the old
numbers.
Pages corrected:
About-the-name, Architecture-deep-dive,
Architecture-first-vs-prompt-first, Case-PtH-Timestomp, FAQ,
Glossary, Home, Live-mode, MCP-function-catalog, Phase-1,
Roadmap, SIFT-adapter-layer, The-Memex-Bet, _Sidebar, dart-mcp
Phase-1.md version history table preserves the historical numbers
(v0.4 = 35 native, v0.5 = 60 functions) as those are historical
facts, not current state.
MITRE coverage also corrected from 11/12 -> 10/12 (TA0009 Collection
and TA0011 C2 are Phase 2).
wiki(qa-r14): kill 'pytest.raises(ToolNotFound)' hallucination in 2 architecture pages
Round 14 of QA — every Python code block in the wiki dry-run-tested
against actual imports.
== Defects fixed ==
### Architecture-deep-dive.md and Architecture-first-vs-prompt-first.md
Both pages had a Python sketch using:
with pytest.raises(ToolNotFound):
call_tool('execute_shell', ...)
ToolNotFound is NOT an exception class in this codebase. The
actual implementation in dart_mcp/__init__.py line 109 is:
raise KeyError(f"ToolNotFound: '{name}' is not exposed by dart-mcp")
i.e., the string 'ToolNotFound' is a marker inside a KeyError
message, not a class name. The real test pattern in
tests/test_mcp_bypass.py is:
try: call_tool(forbidden, {})
except KeyError as e: assert 'ToolNotFound' in str(e)
A judge copying the wiki sketch would get NameError: name
'ToolNotFound' is not defined. Fixed both pages to use the actual
KeyError-with-marker-string pattern from the real test. Verified
by running both rewrites against a real call_tool import — both
pass.
### Other Python blocks reviewed and verified
- dart-audit.md AuditLogger usage: ✅ executes (round-10 fix
holds)
- Operator-guide.md DuckDB query and dart-corr.md DuckDB Why
block: 🟢 illustrative placeholders ('<case>.duckdb',
'auth.csv') — wrapped in operator-context narrative; not
runnable as-is, but the placeholder syntax (<...>) and
surrounding prose make the intent clear. Left as-is.
- SIFT-adapter-layer.md and dart-corr.md '# Illustrative' block:
🟢 schema sketches in a python code fence (no exec semantics).
Left as-is.
== Verification ==
Both fixed sketches manually executed in a Python REPL with
'from dart_mcp import call_tool' first. Both pass. The fixed
pattern is identical (modulo formatting) to what
tests/test_mcp_bypass.py::test_unregistered_destructive_function_raises_ToolNotFound
actually does — so the wiki teaches the real pattern, not a
fictional one.
== Pattern internalised (continuing the round-9/10 thread) ==
Round 9 caught output-key hallucinations (function returns 'flags',
not 'findings').
Round 10 caught argument-name and file-path hallucinations
(host=, target=, --hunt, run_loop, loop.py).
Round 14 caught exception-class hallucinations (ToolNotFound class
that doesn't exist; the real implementation uses KeyError + a
marker string).
The unifying pattern: any wiki/docs Python sketch that names a
specific symbol (function, kwarg, class, file path) needs to be
diff-verified against the actual code. Sketches that just use
'placeholder.csv' or '<case>.duckdb' are fine because they
declare themselves as illustrative.
wiki QA pass: synchronize 13 pages to v0.5 reality (60 tools, 22 tests)
Companion to main repo commit 52f975d (v0.5.1 QA pass).
Updated to reflect the v0.5 SIFT adapter layer (35 native + 25 SIFT
= 60 typed read-only MCP tools) and the v0.5 test suite expansion
(20 → 22 cases):
About-the-name.md
'The 35 typed dart-mcp functions cover...' →
'The typed dart-mcp surface (35 native + 25 SIFT Workstation
adapters = 60 functions) covers...'
Test count 20/20 → 22/22 across all references.
Architecture-deep-dive.md
ASCII architecture box: 'dart-mcp 35 typed forensic functions'
→ 'dart-mcp 60 typed forensic functions (35 native + 25 SIFT)'
Architecture-first-vs-prompt-first.md
'The MCP surface is exactly 35 functions, by name' →
'The MCP surface is exactly 60 typed functions, by name (35
native + 25 SIFT Workstation adapters)'
Case-PtH-Timestomp.md (2 references) updated parallel to docs/.
FAQ.md
Question heading: 'Is the MCP surface really exactly 35
functions?' → 'Is the MCP surface really fixed in size?'
Answer body: counts updated to 60 / 22-22.
Glossary.md
dart-mcp definition: 35 → 60.
'For Agentic-DART v0.4: exactly 35' →
'For Agentic-DART v0.5: 60 (35 native + 25 SIFT Workstation
adapters)'
Home.md (TOC)
'the 35 forensic functions, schema, bypass tests' →
'the 60 forensic functions (35 native + 25 SIFT adapters),
schema, bypass tests'
'why the MCP surface is exactly 35 functions, not 28, not 35'
rephrased to avoid count-anchoring.
Live-mode.md (2 references) parallel to docs/.
MCP-function-catalog.md
Page title: '· 35 typed forensic functions'
→ '· 60 typed forensic functions (35 native + 25 SIFT
Workstation adapters)'
Operator-guide.md
'All 20 tests should print OK' → 'All 22 tests should print OK'
Phase-1.md
Body: '35 typed forensic functions' / '20 of 20 tests passing'
counts updated.
Timeline table: ADDED row for 2026-05-02 v0.5 (SIFT Workstation
tool adapter layer → 60 functions, 22 tests passing). v0.4
historic row preserved verbatim.
Roadmap.md
Three references to 35 / 20-20 updated to v0.5 numbers.
Running-on-macOS.md
'Step 3 — Run all 20 tests' → '... 22 tests'
'All 20 tests pass on M1/M2/M3' → 'All 22 tests pass on M1/M2/M3'
The-Memex-Bet.md
'MCP surface (35 typed functions)' →
'MCP surface (60 typed functions: 35 native + 25 SIFT adapters)'
'The 35 functions are not a guideline...' →
'The 60 functions (35 native + 25 SIFT Workstation adapters)
are not a guideline...'
_Sidebar.md
Two TOC labels: '(35 functions)' → '(60 functions: 35 native +
25 SIFT)'
dart-mcp.md
'exposes exactly 35 typed forensic functions' →
'exposes 60 typed forensic functions (35 native + 25 SIFT
Workstation adapters)'
Section heading 'The 35 functions' → 'The 60 functions (35
native + 25 SIFT adapters)'
SIFT-adapter-layer.md
Preserved verbatim — line 18 'its own 35 forensic functions'
is historic context describing the pre-v0.5 state.
wiki: comprehensive sync 31 → 35 across all pages
v0.4 raised the function count from 31 to 35. Wiki was tracking
old number on multiple pages:
About-the-name.md 'existing 31 functions stay' → 35
Architecture-deep-dive.md 'the 31 typed' → 35
Architecture-first-vs-prompt-first.md '31 functions, by name' → 35
FAQ.md 'is the surface really exactly 31?' → 35
Home.md 'the 31 forensic functions' → 35
Operator-guide.md '31' → '35'
Roadmap.md '31 typed forensic functions' → 35
Threat-model.md (no 31 references — already clean)
dart-mcp.md 'exactly 31 typed' → '35'
MCP-function-catalog.md (header was already 35)
Roadmap also gets a 'v0.4 (2026-04-30)' entry in the Done list to
record the Linux+macOS expansion.
feat: full wiki — Architecture / Operator / Threat model / Roadmap
Five pages, sidebar, written as long-form complement to the README:
Home landing + project status
_Sidebar navigation visible on every page
Architecture-deep-dive why the architecture is shaped this way
Operator-guide run dart-agent on a real SIFT case
Threat-model honest scope of the read-only MCP boundary
Roadmap phase 1-4, anti-roadmap (what we refuse)
Same voice as the README. No marketing language, no overclaim.
The threat model in particular is deliberately honest about what
the architecture does NOT defend against.