Matchmaking Intelligence Platform · research & design reference

How the Matching Engine Works

Every design decision below traces to a named paper, standard, or spec section — and to the file that implements it. Nothing here is retrofitted: the platform’s spec cited its research foundations before a line of code existed.

The build follows two layers of grounding. Tier A is the platform’s own stated research foundations — written into docs/concept/Matchmaking_Intelligence_Platform_Revision_5.md §19 as design principles, each already citing sources, before implementation began. Tier B is the algorithm level: the specific published method or standard each running module actually follows.

Grounding is not the same as completeness. CLAUDE.md scopes this build to Level 1 matching, capacity, and a deterministic decision layer — explicitly excluding learned ranking and graph methods. Where a cited principle points toward something out of that scope, it is marked deferred below rather than quietly skipped or overclaimed.

In plain terms

Every feature in this platform is backed by a specific published paper or standard — not a guess or a hunch. The tables below name the paper, name the file that implements it, and say plainly whether that feature is actually built, only partly built, or deliberately left for later.

implemented running in the code, referenced file exists and is tested partial the principle is honored in part; the full method described in the reference is not built deferred intentionally out of scope per CLAUDE.md, not built

Why — the platform’s stated research foundations

Thirteen of the eighteen design principles in spec §19 map to a concrete piece of this build. Citation keys jump to the full reference below.

Design principles mapped to research references, a plain-language description, and implementation status
Principle	Grounded in	Status
Two-sided reciprocal markets§19.2 Both sides have to want the match — a great candidate who doesn’t want what’s on offer isn’t actually a good match. `engine/scoring/directional.py` — a→b and b→a scored separately, combined by harmonic mean	R1 R2 R3	implemented
Reciprocity must be directional§19.16 What A needs from B differs from what B needs from A, so each direction is checked on its own before the two are combined. `engine/scoring/directional.py` — needs→capabilities and preferences→opportunity compared separately, never symmetric similarity alone	R3	implemented
Rank, don’t just classify§19.3 The goal is ordering candidates best-to-worst for a specific ask — not just sorting them into “good” and “bad” piles. every response returns ordered candidates, but via a deterministic weighted score + MMR — not a learned ranker. `learned: null` on every response, per hard rule 1.	R4	deferred
Beyond accuracy: diversity & serendipity§19.4–19.5 A list that’s technically accurate but shows five near-identical candidates isn’t actually useful, so the system deliberately mixes in variety. `engine/rerank/mmr.py` — λ=0.7 default, 0.5 under the “exploratory” strategy control	R5 R6 R7	implemented
Guard exposure / popularity feedback loops§19.6 If the same few entities get shown over and over, they start looking “popular” just because they were shown a lot, not because they’re better. The system caps how often anyone gets shown. `engine/capacity/`, `evals/evals/exposure.py` — exposure counters (30/entity/7d), congestion discount, top-5%-share report	R8	implemented
Model multiple stakeholders§19.7 A match affects more than the person asking for it — the person recommended, the project owner, and the platform all have a stake. capacity/exclusion logic weighs both sides of a match; no separate multi-stakeholder optimization objective is computed	R9	partial
Constraint / preference / intent / strategy / presentation taxonomy§19.9 “Must have X” means something different from “prefer X,” which is different from “show me more options.” The system treats each kind of instruction differently instead of lumping them together. `shared/mip_shared/policy_validation.py` — precedence app > project > user, tighten-only; preferences rerank, never silently filter	R10	implemented
Separate compatibility, feasibility, outcome§19.10 Being a great fit on paper, actually being available right now, and being likely to succeed are three different questions — kept as three different answers, not blended into one number. base score, capacity exclusion, and (absent) outcome probability kept as distinct fields across the base/adjusted/delivered snapshots	—	implemented
Scores are not calibrated probabilities§19.11 A score of 82 doesn’t mean “an 82% chance of success” — it just means this candidate ranks above one scored 75. satisfied by omission — no probability head exists; responses expose ordinal scores only	R6	implemented
Explanation, counterfactuals, controllability§19.12 Every result comes with a plain reason it ranked where it did, and what would need to change for it to rank higher. `engine/explain/` — template explanations + counterfactuals, capped at 2 per result	R10 R14	implemented
Graph augments, doesn’t replace§19.15 Looking at who’s connected to whom could add a useful signal later — but it’s not built yet, and it’s meant to add to this approach, not replace it. explicitly out of scope — `CLAUDE.md` hard rule 1: no Levels 2–4 or graph	R11	deferred
De-identification limits in small populations§19.17 In a small market, even “anonymous” details can accidentally point to one real person (“the only robotics founder in town”). Removing names alone isn’t automatically enough. tokenization + vault encryption implemented; explicit k-anonymity thresholding of quasi-identifiers for a released analytics corpus is not yet built	R13	partial
Evidence provenance & uncertainty as first-class§19.18 The system tracks not just what it knows about someone, but how sure it is and where that information came from. `engine/scoring/confidence.py` — evidence confidence value carried per result, distinct from compatibility	R6 R10	implemented

How — algorithms behind the running code

Where the code is a faithful implementation of the cited method, that’s stated plainly. Where it follows the same problem framing with a simpler mechanism, that’s stated too.

Implemented algorithms mapped to their published or standardized source, a plain-language description, and reference
Technique	Reference
Diversity reranking (MMR) After ranking by relevance, the list gets reshuffled slightly so it doesn’t show five near-duplicates in a row. `engine/rerank/mmr.py` — direct implementation of the original formula: λ·sim(d,q) − (1−λ)·max sim(d, selected)	I1
Weighted hybrid base score The final score blends two things — how semantically similar two profiles are, and how much they seem to want the same kind of relationship — in a fixed, adjustable ratio. `engine/scoring/directional.py` §5.2 — w_sem·semantic + w_rec·reciprocal, a “weighted hybridization” in Burke’s taxonomy	I5
Directional reciprocal aggregation Two one-way scores — does A want what B offers, and does B want what A offers — are combined so a lopsided match pulls the final score down, instead of a strong one-sided score hiding a weak other side. `engine/scoring/directional.py` — harmonic mean of a→b, b→a	R3
Sentence embeddings Turns each text profile into a list of numbers that captures its meaning, so “similar meaning” becomes something a computer can measure. `worker/app/embeddings.py` — pinned `bge-small-en-v1.5` (I2); descends from the siamese bi-encoder paradigm SBERT established (I4, lineage)	I2 I4
Approximate nearest-neighbor retrieval Instead of comparing a candidate against every profile in the database, an index quickly finds the ~100 most likely matches first. `engine/scoring/db.py` — pgvector index backing the top-100 candidate set, the HNSW graph-search family	I3
Deterministic pseudonymization Turns a name into a fixed, non-reversible code — the same person always gets the same code, but the code alone can’t be turned back into the name. `gateway` tokenizer — per-tenant `entity_token` (`ENT_<12 hex>`), keyed and deterministic	I6
Exposure / position fairness Being shown near the top of a list isn’t free — it uses up a limited “exposure budget,” so the same top candidates aren’t shown to everyone forever. `engine/capacity/` — same problem framing as I8, a simpler mechanism (fixed budget + rotation, not an LP-based optimizer)	I8
Rank-agreement evaluation Compares the system’s ranking to a human expert’s ranking of the same candidates, and produces one number for how closely they agree. `evals/evals/agreement.py` — Kendall’s τ via `scipy.stats.kendalltau`, engine ranking vs. blind expert panel	I7
Deterministic, non-learned decision layer The ranking math never calls an AI model — it’s fixed arithmetic every time, so identical inputs always produce the identical output and it can be audited line by line. `CLAUDE.md` hard rule 4 — “no LLM calls inside scoring, ranking, policy application, explanation, or counterfactuals”	I9

III

Regulatory & standards anchors

Not academic papers, but the specific legal and technical standards the privacy design is built against.

RFC 2104 — HMAC keyed-hashing: The construction behind deterministic entity tokenization (I6). Plainly: a one-way, key-locked scrambler for turning a name into a code.
RFC 4880 — OpenPGP message format: The encryption scheme pgcrypto implements for the per-tenant identity vault. Plainly: the lockbox format the real names are stored in.
GDPR Art. 4(5) — definition of pseudonymization: The legal definition the token design is built to satisfy. Plainly: data that can’t be traced back to a person without a separate, protected key.
GDPR Art. 22 & Art. 25 — automated-decision transparency, privacy by design: Motivates the deterministic scoring pipeline and the explanation/counterfactual trail on every result. Plainly: if a computer makes the call, it has to be able to explain the call.
Quebec Law 25: Cited directly in the platform spec (§19.12) as the compliance context for explainability and controllability.
HIPAA Safe Harbor, 45 CFR §164.514: The closest legal analogue to “no raw identity past the gateway.” Plainly: a defined line past which identifying details are not allowed to cross.

References

R1–R14 are reproduced verbatim from the platform spec’s own §21. I1–I9 are added here, at the implementation level, and independently verified. Each entry carries a plain-language gloss below the formal citation.

Design rationale — `Matchmaking_Intelligence_Platform_Revision_5.md` §21

R1Gale, D., & Shapley, L. S. (1962). College Admissions and the Stability of Marriage. The American Mathematical Monthly, 69(1), 9–15. jstor.org/stable/2312726The original proof that two groups with different preferences (like students and colleges) can always be paired up so no pair would rather swap partners — the founding result of matching theory.
R2The Royal Swedish Academy of Sciences. (2012). Stable Allocations and the Practice of Market Design. Scientific Background, Sveriges Riksbank Prize in Economic Sciences.The Nobel committee’s own plain-language explainer for why the 2012 Economics Prize (Roth & Shapley) mattered.
R3Palomares, I. (2020). Reciprocal Recommendation: Matching Users with the Right Users. SIGIR ’20, 2429–2431. doi.org/10.1145/3397271.3401420A short survey defining what makes a recommendation “reciprocal” — both people have to like the match, not just one.
R4Swezey, R. M. E., Grover, A., Charron, B., & Ermon, S. (2021). PiRank: Scalable Learning to Rank via Differentiable Sorting. NeurIPS 34.A machine-learning technique for training a ranking model to directly optimize “is the list in the right order,” instead of an indirect stand-in metric.
R5Kaminskas, M., & Bridge, D. (2016). Diversity, Serendipity, Novelty, and Coverage: A Survey and Empirical Analysis of Beyond-Accuracy Objectives in Recommender Systems. ACM TiiS, 7(1), Art. 2. doi.org/10.1145/2926720Argues recommender systems should be judged on more than accuracy alone — also variety, surprise, and how much of the catalog gets a fair shot.
R6Steck, H. (2018). Calibrated Recommendations. RecSys ’18, 154–162. doi.org/10.1145/3240323.3240372Netflix research showing that if a system only ever recommends someone’s single favorite genre, the list stops reflecting what they actually like — recommendations should mirror the real mix of a person’s taste.
R7Zangerle, E., & Bauer, C. (2022). Evaluating Recommender Systems: Survey and Framework. ACM Computing Surveys, 55(8), Art. 170. doi.org/10.1145/3556536A survey of the many ways researchers evaluate recommender systems, and a framework for picking the right ones.
R8Mansoury, M., Abdollahpouri, H., Pechenizkiy, M., Mobasher, B., & Burke, R. (2020). Feedback Loop and Bias Amplification in Recommender Systems. CIKM ’20. doi.org/10.1145/3340531.3412152Shows recommenders can create a feedback loop: showing something more makes it look more popular, which makes the system show it even more — whether or not it’s actually better.
R9Ranjbar Kermany, N., et al. (2021). A Fairness-Aware Multi-Stakeholder Recommender System. World Wide Web. doi.org/10.1007/s11280-021-00946-8A recommender system designed to be fair not just to the person searching, but to everyone affected by the recommendation.
R10Ge, Y., Liu, S., Fu, Z., Tan, J., Li, Z., Xu, S., Li, Y., Xian, Y., & Zhang, Y. (2024). A Survey on Trustworthy Recommender Systems. ACM Transactions on Recommender Systems. doi.org/10.1145/3652891A survey defining what it means for a recommender system to be “trustworthy” — fairness, privacy, explainability, and robustness treated as one connected package.
R11Duricic, T., Kowald, D., Lacic, E., & Lex, E. (2023). Beyond-Accuracy: A Review on Diversity, Serendipity and Fairness in Recommender Systems Based on Graph Neural Networks. arxiv.org/abs/2310.02294A survey on using graph methods — who’s connected to whom — to add diversity and fairness to recommendations.
R12Chen, J., Dong, H., Wang, X., Feng, F., Wang, M., & He, X. (2020). Bias and Debias in Recommender System: A Survey and Future Directions. arxiv.org/abs/2010.03240A catalogue of the different kinds of bias that creep into recommender systems, and ways to correct for them.
R13Sweeney, L. (2002). k-Anonymity: A Model for Protecting Privacy. International Journal of Uncertainty, Fuzziness and Knowledge-Based Systems, 10(5), 557–570. doi.org/10.1142/S0218488502001648Defines “k-anonymity”: a record is only truly anonymous if it’s indistinguishable from at least k−1 other records on the details that could identify someone.
R14Wachter, S., Mittelstadt, B., & Russell, C. (2018). Counterfactual Explanations Without Opening the Black Box: Automated Decisions and the GDPR. Harvard Journal of Law & Technology, 31(2), 841–887.Argues that under GDPR, people are entitled to a “counterfactual” explanation of an automated decision — not just why, but what would need to change for a different outcome.

Implementation-level — added for this build, verified independently

I1Carbonell, J., & Goldstein, J. (1998). The Use of MMR, Diversity-Based Reranking for Reordering Documents and Producing Summaries. SIGIR ’98, 335–336.The original formula for balancing “most relevant” against “not too similar to what’s already been shown” when building a ranked list.
I2Xiao, S., Liu, Z., Zhang, P., & Muennighoff, N. (2023). C-Pack: Packaged Resources to Advance General Chinese Embedding. arxiv.org/abs/2309.07597The paper behind the BGE embedding model family, including bge-small-en-v1.5, the one this platform uses to turn text profiles into comparable vectors.
I3Malkov, Y. A., & Yashunin, D. A. (2016). Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs. IEEE TPAMI (2018). arxiv.org/abs/1603.09320The search-index technique that makes it fast to find “the closest matches” among millions of vectors, without comparing against every single one.
I4Reimers, N., & Gurevych, I. (2019). Sentence-BERT: Sentence Embeddings Using Siamese BERT-Networks. EMNLP-IJCNLP 2019. arxiv.org/abs/1908.10084Showed how to adapt language models so two pieces of text with similar meaning end up with mathematically similar vectors — the lineage modern embedding models like the one this platform uses build on.
I5Burke, R. (2002). Hybrid Recommender Systems: Survey and Experiments. User Modeling and User-Adapted Interaction, 12(4), 331–370.A survey of ways to combine multiple recommendation signals into one score — this platform’s semantic-plus-reciprocal blend is a textbook example of one such method (“weighted hybridization”).
I6Krawczyk, H., Bellare, M., & Canetti, R. (1997). HMAC: Keyed-Hashing for Message Authentication. IETF RFC 2104. rfc-editor.org/rfc/rfc2104The internet standard for turning any piece of data into a fixed, secret-key-dependent code — the basis for this platform’s tokenization.
I7Kendall, M. G. (1938). A New Measure of Rank Correlation. Biometrika, 30(1/2), 81–93.The original statistic for measuring how much two rankings of the same items agree with each other.
I8Singh, A., & Joachims, T. (2018). Fairness of Exposure in Rankings. KDD ’18, 2219–2228. doi.org/10.1145/3219819.3220088Argues that being ranked near the top of a list is itself a scarce resource, and should be shared out fairly over time — not handed permanently to whoever scored highest once.
I9Rudin, C. (2019). Stop Explaining Black Box Machine Learning Models for High Stakes Decisions and Use Interpretable Models Instead. Nature Machine Intelligence, 1(5), 206–215. doi.org/10.1038/s42256-019-0048-xArgues that for high-stakes decisions, it’s better to build a model that’s simple and explainable from the start than to build a complex “black box” and try to explain it afterward.