Mediabot’s Plugin API v3 has left the Quote Vault for its next carefully guarded chamber. With MB758, plugins gain a new core-owned capability: data.factoids.read.

This is not a mass unlocking spell. No factoid command has moved into a plugin, no package receives the capability automatically, and no database handle has escaped from the castle. Instead, MB758 establishes a narrow, testable doorway through which future plugins may read approved factoid data without learning the secrets of the underlying SQL dungeon. 🔐

Three spells, no hidden passageways

The new facade exposes exactly three operations:

• exact lookup by keyword;
• an alphabetically ordered keyword list, capped at 60 results;
• a top-recall view, capped at 10 results.

The active invocation policy supplies the IRC channel. A plugin cannot quietly name a different channel, submit arbitrary SQL, or obtain Mediabot’s database connection. Optional glob patterns are validated and translated by the core; literal SQL wildcards remain safely escaped.

Exact matches return an immutable FactoidRecordV3. The record contains only detached data: the factoid ID, keyword, value, copied author identity, timestamps, and recall count. Lists and rankings likewise return copied, bounded values rather than live internal objects.

In other words, the librarian hands over a copied index card—not the key to the Restricted Section. 🗝️📖

Observation without disturbing the shelves

Read operations may run while a plugin is in observe mode. This lets a future package compare behavior safely before becoming visible on IRC.

Crucially, these reads are genuinely side-effect-free. They do not increment a factoid’s recall counter, modify attribution, or write any other state. An off policy still closes the door completely, while missing capabilities fail before the factoid service is reached and remain visible to operators through bounded diagnostics.

MB758 deliberately keeps several stronger spells outside the boundary:

• whatis still carries recall-counter behavior and is not migrated;
• learn remains a write operation;
• forget remains a permission-sensitive delete operation;
• no factoids-v3 package is introduced yet;
• no live plugin policy or stored factoid is changed.

That separation matters. A read capability should not smuggle in a write merely because the historical command happened to combine both. The Ministry gateway now describes what a plugin may do, not which legacy function it happened to call. ⚖️

A second domain proves the architecture

Until now, Quotes carried most of the domain-facade work. MB758 proves that the same model can serve another Mediabot feature without exposing broad bot internals.

The runtime now wires a dedicated factoid-read sink through PluginContext and PluginManager to FactoidServiceV3. The manager allows only the three named operations, derives channel scope from policy, converts service failures into a neutral unavailable result, and records bounded logs and metrics. The machine contract and author documentation publish those limits explicitly.

This is the architectural result that matters most: Plugin API v3 is becoming a collection of small, reviewable authorities rather than a new route back to the entire monolith. 🏰

The examination results ✅

The owls returned with a flawless stack of parchment:

• targeted Factoid and API v3 tests: 949/949 passed;
• fast validation lane: 7,642/7,642 passed;
• final full suite: 20,180/20,180 passed across 996 test files;
• development service restarted successfully and reported active.

The final commit was pushed to master as:

4b34a0f MB758: open the Restricted Section to factoid readers 📚🪄

The development version advanced to 3.6dev-20260921_160055.

What comes next? 🔮

The next reviewed milestone can introduce an inert factoids-v3 package and adopt only the pure factoid and factoids readers behind the existing reversible policy bridge. whatis should wait for an explicit recall-accounting authority, while learn and forget deserve their own separately reviewed write capability.

For now, the shelves are readable, the locks still know exactly whom they serve, and not a single factoid has been transfigured along the way. ✨