mikronova/funnel-core

funnel-core — for beginners

No jargon. What this little library is and why it exists.

The one-sentence version

funnel-core turns a list of things that happened ("someone submitted an idea", "a plan was made", "a task finished") into an answer to a question ("what should I work on next?", "show me the kanban board", "which bugs are still open?").

The mental picture

Think of a diary. Each line is one small fact, written once and never erased:

- rickard had an idea: "add a dark theme"
- we made a plan for it
- the plan has 3 tasks: A, then B, then C
- task A is finished

funnel-core reads the whole diary from the top and rebuilds the current picture in memory. That picture is called a Funnel. You never edit the picture directly — you add a new diary line (an Event) and re-read.

It also refuses lines that don't make sense — a task that depends on itself, the same dependency written twice, or a loop ("A waits for B, B waits for A"). A loop is the nasty one: nothing in it can ever start, so the whole plan would freeze. funnel-core spots the loop the moment you try to add the line that would close it and says no, keeping every plan finish-able.

What you get out of it

Once the diary is read, you can ask for different views of the same facts:

• History — the list of everything submitted, newest first.
• Board — a kanban board with columns (Inbox → Accepted → Proposed → Planned → Dropped), each idea/task sitting in the right column.
• Cards + search — every item as a card, filterable with a search box like type:bug is:open for:me (the same style GitHub/JIRA use).
• "What's next?" — the tasks whose prerequisites are all done, in the right order (task B only shows up once task A is finished).
• Plan-DAG — the boxes-and-arrows diagram the nornir app draws.
• The critical path — the longest run of "this task must finish before that one can start". It's the chain that decides how long the whole plan takes: make it shorter and everything finishes sooner. The library can point right at it. There are two flavours: one counts from the original idea down through its tasks (how deep is the whole plan), and a dependency-only one that ignores the idea and counts just the "task waits on task" hops (how deep is the actual work). The work-only chain is always the same length or shorter.
• Slack — for every task, how many "rounds" late it could start without making the whole plan finish later. A task with zero slack is on a longest chain — it's a bottleneck you can't afford to delay; the library lists all of them. A task with slack 2 has two rounds of wiggle room a scheduler can use.
• Bottlenecks — "which task, if I finished it next, would free up the most other work?" The library counts, for every box, how many other boxes are stuck waiting behind it (directly or further down the line) and ranks them, biggest first. The top one is where a human should push. A surprising-but-true rule falls out: a task that feeds one long chain beats a task that feeds three dead-end leaves — because the long chain has more work stalled behind it, even though the other task points at more arrows right now. So "unblocks the most" isn't just "has the most arrows".
• What changed — hand the library the old version of a plan and it tells you the difference to the new one: which tasks were added or removed, which dependency arrows appeared or disappeared, and which surviving tasks changed (renamed, finished, or re-wired). If nothing changed, the difference is empty. This is what a "re-plan" screen shows so you can see a revision at a glance.
• The growth story — read the diary line by line and the library tells you, for every box and arrow in the diagram, which line it first showed up on. Since the diary only ever adds things (never erases), the diagram only ever grows. That's exactly what you need to play the diagram building itself like a little movie — boxes popping in in order — and to drag a slider back through history to see how the plan looked at any earlier moment. It also gives you a simple running count ("3 boxes so far, then 4, then 4 with an arrow…") for a progress line. There are two ways to get this movie. The batch way reads the whole diary at once — perfect when you open an old plan and want the finished movie or a history slider. The live way is for watching it happen right now: you hand the library one new diary line each time it's written and it tells you just the boxes that popped in on that line — no re-reading the whole diary every time. Both ways produce the exact same movie frame-for-frame (the library checks this), so a screen can start with the batch movie and then keep growing it live line by line.

Joining the plan to the actual code

Here's a thing the diary alone can't tell you: which files/crates does this plan actually touch?

Picture two diagrams side by side. On the left, the plan: boxes like "write the importer", "fix the crash". On the right, the code: boxes like funnel-core, nornir, nornir-viz, with arrows showing which one needs which. Now imagine drawing a string from a plan box across to a code box: "this task touches that crate." That string is a wire, and the pile of them is the wiring.

Once the strings are there you get two useful answers:

• Blast radius. Pick a plan box, follow its strings to the code boxes, then keep walking the code arrows backwards — to everything that depends on those boxes. That's everything that might break. Touch funnel-core and you've touched nornir, and therefore nornir-viz, and therefore the app.
• Who owns this crate? Go the other way: a crate with lots of changes and no string attached to any plan box is work nobody planned.

The part that matters most: admitting what isn't wired

It would be very easy — and very dishonest — for the library to look at a plan box with no string attached and cheerfully report "affects nothing". Empty because there's genuinely nothing downstream, and empty because nobody wired it up, are completely different answers that look identical.

So the library refuses to conflate them. Every plan box is listed as either mapped (has a string) or unmapped (doesn't), with a reason for the second:

• no wire — nobody ever connected it. Just a gap.
• only proposed — the computer guessed a connection but no human has said yes. A guess is not a fact, so it doesn't count yet.
• only rejected — someone looked at the guesses and threw them all away. Needs a fresh one.
• dangling — there is a confirmed string, but it's tied to a crate that doesn't exist (renamed, typo). This is the nastiest one, because at a glance it looks fine.

And there's one row the library shouts about: a task marked finished that was never wired to anything. That means work landed in code the plan can't point at.

Strings are never deleted, by the way — the diary never erases. Rejecting a connection is just a new line saying "no, not that one", which is how the computer remembers not to suggest it again.

Why it's built this way

Because the answer is always computed fresh from the facts, the same diary always gives the same answer — no surprises, nothing hidden, and it's trivial to test. And because it holds none of the heavy machinery (no database, no graphics), both the big nornir app and the ordning app can use the exact same rules for free.