Semantic classification

Entry point of the deterministic keyword inspection engine. It loads policy, applies the overlay and registry, normalises text, runs the classifiers, aggregates results and picks an action. Stateless, with a fail-closed catch-all and no LLM or network use.

What it does

policy load → overlay → registry → normalise → classifiers → aggregate → action

Depends on

policy, registry, scoring, evidence, metrics

State

none (stateless)

Safeguards

fail-closed catch-all; no LLM/network invariant

Returns DENY SEMANTIC_INSPECTION_UNAVAILABLE when policy, registry, normalisation, aggregation, action, evidence or any other internal step faults. It logs CRITICAL, bumps 2 counters and records failure evidence; an inspection failure never becomes ALLOW.

What it does

returns DENY SEMANTIC_INSPECTION_UNAVAILABLE

Inputs

any internal fault

Outputs

CRITICAL log, 2 counters, failure evidence

Depends on

metrics, logger

Safeguards

never ALLOW on inspection failure

Engine kill switch: when QODIQA_SEMANTIC_POLICY_ENABLED is false, the engine returns an ALLOW verdict instead of inspecting. The switch is flagged SEM_FORBIDDEN_IN_PROD, so production does not accept it.

What it does

false →

Inputs

QODIQA_SEMANTIC_POLICY_ENABLED

Outputs

ALLOW verdict

Depends on

env

Safeguards

SEM_FORBIDDEN_IN_PROD

Caveat SEM_FORBIDDEN_IN_PROD

Parses the tier thresholds and enforcement flags from 7 env vars, with defaults of 0.35, 0.55 and 0.70, into a frozen policy object. Overrides that are forbidden in production are refused.

What it does

parse with defaults 0.35/0.55/0.70

Inputs

7 env vars

Outputs

frozen policy object

Depends on

env

Safeguards

prod-forbidden overrides

Caveat prod-forbidden overrides

Resolves an aggregate result and the policy into DENY, REVIEW, WARN or ALLOW. By default WARN escalates to a block for PROMPT_INJECTION and SYSTEM_PROMPT_EXTRACTION.

What it does

DENY/REVIEW/WARN/ALLOW mapping

Inputs

aggregate result, policy

Depends on

policy

Safeguards

WARN-escalate default PROMPT_INJECTION + SYSTEM_PROMPT_EXTRACTION

Computes classifier confidence with a noisy-OR, 1−Π(1−w), over the signals matched in the normalised text. It returns the confidence and the matched tags.

What it does

1−Π(1−w)

Inputs

normalised text, signals

Outputs

confidence, matched tags

Multiplies confidence by severity to get a weighted score, then maps the score onto decision tiers. It returns both the weighted score and the decision.

What it does

×; tiers

Inputs

confidence, severity

Outputs

weighted score, decision

Aggregates classifier results by sorting them and taking the top one as the maximum. The aggregate is what the later action step works from.

What it does

sort, top = max

Inputs

classifier results

Outputs

aggregate

Runs each classifier with try/catch, monotonic timing and output validation, with a post-hoc timeout. Invalid or slow results are discarded and never silently allowed; outcome counts and failures are returned.

What it does

try/catch, monotonic timing, output validation

Inputs

classifiers, ctx, policy

Outputs

outcome counts/failures

Safeguards

invalid/slow results discarded, never silently allowed

Classifier registry that auto-discovers classifiers, supports runtime registration and a disable list. It requires all modules and reports status OK or LOAD_FAILED; a load failure or an empty registry fails closed.

What it does

require all; status OK/LOAD_FAILED

Inputs

dir listing

Outputs

classifier list

Depends on

fs

Safeguards

load failure/empty → fail-closed

Declarative classifier factory: validates a classifier definition, scores it and refines the score. It validates the definition at load and returns a frozen classifier.

What it does

validate, score, refine

Inputs

def

Outputs

frozen classifier

Safeguards

validates definition at load

Credential-extraction classifier with 4 inline signals plus 13 i18n ones. It flags signals only and reports CRITICAL CREDENTIAL_EXTRACTION for normalised text.

What it does

signals only

Inputs

normalised text

Outputs

CRITICAL CREDENTIAL_EXTRACTION

Depends on

i18nSignals

Data-exfiltration classifier with 5 signals, matching on signals only. It reads normalised text and reports the severity CRITICAL with the reason DATA_EXFILTRATION, with no co-occurrence refinement.

What it does

signals only

Inputs

normalised

Outputs

CRITICAL DATA_EXFILTRATION

File-enumeration classifier with 4 signals plus 2 refinements adding 0.45. It also looks for traversal and sensitive-path co-occurrence, and reports HIGH FILE_SYSTEM_ENUMERATION.

What it does

signals + traversal/sensitive-path co-occurrence

Inputs

normalised

Outputs

HIGH FILE_SYSTEM_ENUMERATION

Impersonation classifier with 4 signals, matching on signals only. It reads normalised text and reports MEDIUM IMPERSONATION_ATTEMPT. Matching is on signals only, with no refinement step.

What it does

signals only

Inputs

normalised

Outputs

MEDIUM IMPERSONATION_ATTEMPT

Jailbreak classifier with 9 inline signals plus 14 i18n ones, matching on signals only. It reports HIGH JAILBREAK_ATTEMPT for normalised text.

What it does

signals only

Inputs

normalised

Outputs

HIGH JAILBREAK_ATTEMPT

Depends on

i18nSignals

Memory-extraction classifier with 8 signals and a refinement adding 0.35. It combines signals with co-occurrence on normalised text and reports HIGH MEMORY_EXTRACTION.

What it does

signals + co-occurrence

Inputs

normalised

Outputs

HIGH MEMORY_EXTRACTION

PII-extraction classifier with 3 signals and a refinement adding 0.35. It combines signals with co-occurrence on normalised text and reports CRITICAL PII_EXTRACTION.

What it does

signals + co-occurrence

Inputs

normalised

Outputs

CRITICAL PII_EXTRACTION

Policy-bypass classifier with 8 signals and a refinement adding 0.30. It combines signals with scope and negation co-occurrence and reports HIGH POLICY_BYPASS_ATTEMPT.

What it does

signals + scope/negation co-occurrence

Inputs

normalised

Outputs

HIGH POLICY_BYPASS_ATTEMPT

Prompt-injection classifier with 8 inline signals plus 25 i18n ones, matching on signals only. It reports HIGH PROMPT_INJECTION_ATTEMPT, and WARN escalates to a block by default.

What it does

signals only

Inputs

normalised

Outputs

HIGH PROMPT_INJECTION_ATTEMPT

Depends on

i18nSignals

Safeguards

WARN escalates to block by default

Security-override classifier with 3 signals plus 26 i18n ones and refinements of +0.35 and +0.20. It looks for a verb with a control noun (up to 200) plus an authority claim, and reports CRITICAL SECURITY_OVERRIDE_ATTEMPT.

What it does

signals + verb/control-noun (≤200) + authority claim

Inputs

normalised

Outputs

CRITICAL SECURITY_OVERRIDE_ATTEMPT

System-prompt-extraction classifier with 6 signals plus 22 i18n ones, matching on signals only. It reports HIGH SYSTEM_PROMPT_EXTRACTION, and WARN escalates.

What it does

signals only

Inputs

normalised

Outputs

HIGH SYSTEM_PROMPT_EXTRACTION

Depends on

i18nSignals

Safeguards

WARN escalates

Tool-abuse classifier with 6 signals and a refinement adding 0.45, using a cased-text path. It checks verb/identifier and verb/bypass co-occurrence (up to 60) and reports HIGH TOOL_ABUSE_ATTEMPT.

What it does

signals + verb/identifier + verb/bypass co-occurrence (≤60)

Inputs

normalised + case-preserved

Outputs

HIGH TOOL_ABUSE_ATTEMPT

Unauthorized-tool-request classifier with 3 signals, matching on signals only. It reads normalised text and reports HIGH UNAUTHORIZED_TOOL_REQUEST when one of them matches.

What it does

signals only

Inputs

normalised

Outputs

HIGH UNAUTHORIZED_TOOL_REQUEST

Lexicon of 100 multilingual attack-phrase signals across 13 languages and 5 concepts. Each is a literal escaped phrase with a weight of .50 to .55, returned as signal arrays by concept name.

What it does

literal escaped phrases weight.50–.55

Inputs

concept name

Outputs

signal arrays

Decodes b64, hex, URL, HTML and u-escape content found in raw text and appends it, to depth 3, up to 50 candidates, with a 200k cap and plain-text validation. Work is bounded against ReDoS and expansion.

What it does

depth 3, ≤50 cand., ×5, 200k cap, plain-text validation

Inputs

raw text

Outputs

appended decoded text, flags

Depends on

Buffer

Safeguards

bounded work (ReDoS/expansion guards)

Folds Unicode, homoglyph, invisible, diacritic and repeated characters (NFKC, a 30-entry confusable table, NFKD, emoji strip) and rebuilds fragments from a 38-word dictionary. Output is normalised text, as evasion hardening.

What it does

NFKC, 30-entry confusable table, evasion-char & emoji strip, NFKD diacritics, repeat collapse, 38-word dictionary rebuild

Inputs

text

Outputs

normalised text

Safeguards

evasion hardening

Case-preserved variant of text normalisation: runs the same pipeline as the standard one, but without lower-casing and without fragment rebuild, so cased text stays available to classifiers.

What it does

same pipeline w/o lower-casing and fragment rebuild

Inputs

text

Produces audit-safe normalisation metadata as boolean flags, emitted when the text changed. It is kept as evidence only, and the evidence carries no text.

What it does

boolean flags

Inputs

text

Outputs

when changed

State

evidence only

Safeguards

no text in evidence

Optional clause-aware co-occurrence gate (H26): checks that two regexes match within a window, and in the same clause when the flag is on. Returns a boolean; production only allows the default.

What it does

proximity (+same clause when flag on)

Inputs

two regexes, window

Outputs

boolean

Depends on

env flag

Safeguards

prod only allows default

Caveat prod only allows default

Orchestrator that runs keyword inspection first, then embedding only if the keyword step did not block, and merges intent-gate evidence. An embedding DENY replaces the verdict; an ALLOW never relaxes a keyword block.

What it does

keyword → embedding only if not blocked

Inputs

prompt, ctx

Outputs

verdict

Safeguards

embedding DENY replaces; ALLOW never relaxes keyword block

Multi-turn screening: each normalised message in the request body is screened on its own, and the first block wins. Produces a verdict, and depends on validation and conversation handling.

What it does

each normalised message screened, first block wins

Inputs

request body

Outputs

verdict +

Depends on

validation/conversation

Gate wrapper that shapes the verdict, fails closed and applies a tenant bar, taking text and ctx and returning a verdict and metrics. Depends on the tenant registry.

Boot and readiness check: verifies hashes, loads and embeds the anchors and validates models, ending as READY, FAILED or DISABLED. SHA-256 pins protect it, and the process exits on FAILED.

What it does

verify hashes, load, embed anchors, validate models

Inputs

anchors, models

Outputs

READY/FAILED/DISABLED; process exit on FAILED

State

in-memory anchors

Safeguards

SHA-256 pins; fatal on failure

Pins the integrity of 4 base-model files by comparing sha256 digests, giving tamper detection. It depends on the file system and crypto.

What it does

sha256 compare

Inputs

files

Depends on

fs, crypto

Safeguards

tamper detection

MiniLM embedding backend on single-thread ONNX, using the @xenova/transformers pipeline with session swap. Turns text into 384-d Float vectors from local files only, with remote loading disabled.

What it does

@xenova/transformers pipeline, session swap

Inputs

text

Outputs

384-d Float vectors

Depends on

onnxruntime-node

Safeguards

local files only, remote disabled

Inference worker pool on worker_threads with least-busy dispatch and a queue of up to 10,000. Sized by QODIQA_INFERENCE_WORKERS (4) and SPLIT_MIN (8); a worker failure rejects its tasks.

What it does

worker_threads, least-busy, queue ≤10,000

Inputs

QODIQA_INFERENCE_WORKERS (4), …SPLIT_MIN (8)

Outputs

vectors

Depends on

worker_threads

Safeguards

bounded queue; worker failure rejects tasks

Per-stream embedding memo: an AsyncLocalStorage LRU of 512 entries held in memory, so repeated text in a stream returns cached vectors.

What it does

AsyncLocalStorage LRU 512

Inputs

text

Outputs

cached vectors

Depends on

async_hooks

State

in-memory

Assembles the anchor set of 76 anchors in 6 families from sampling plus a retire list, using a corpus and 2 anchor files. A surgical retirement set controls what is removed.

What it does

sampling + retire list

Inputs

corpus + 2 anchor files

Outputs

[]

Depends on

files

State

files

Safeguards

surgical retirement set

Windowing at 400/50 with an optional tail: splits long text into overlapping windows and picks the worst window. Full-text coverage is the safeguard.

What it does

overlapping windows, worst-window pick

Inputs

long text

Outputs

window list

Safeguards

full-text coverage

Gate 1 of the embedding path: takes the max cosine against the anchors and compares it with a per-family threshold, returning a score.

What it does

max cosine, family threshold

Inputs

vector

Outputs

score

Depends on

anchors

Gate 2, a logistic head: fires when sigmoid(b+w·v) is above 0.838629 for the vector. Weights come from a json file and are validated at boot.

Gate 3, v9: combines the embedding with 21 surface features, standardised and scaled by 0.05, and fires above 0.688841. A feature-contract drift check runs at boot; weights live in a file.

What it does

standardised features ×0.05

Inputs

vector, text

Outputs

/ (> 0.688841)

Depends on

i18n

State

file

Safeguards

feature-contract drift check at boot

Gate 4, the v5 logistic gate: it fires when the sigmoid of the vector exceeds 0.6006089406965567. Its parameters come from a json file.

OR-combination of the gate outputs: if any gate fires the result is DENY, joining the anchor, head, v9 and v5 results into one decision.

What it does

any-fires → DENY; join of anchor/head/v9/v5

Inputs

gate outputs

Outputs

decision

FT-3 gate, default ON: when the band is 0.2977 or higher and the verdict is ALLOW, checks a fine-tuned encoder family-anchor dot against a threshold on the worst-window text. SHA-256 pinned, and scoring fails closed.

What it does

band ≥0.2977 and ALLOW → FT encoder family-anchor dot ≥ threshold

Inputs

worst-window text

Outputs

ft3* fields, +ft3

Depends on

(sha pinned), tokenizer

State

model file

Safeguards

SHA-256 pin; fail-closed scoring

Optional FT-2 gate, default OFF but re-enableable: same checks as FT-3 using the FT-2 model and thresholds. SHA-256 pinned, and production forbids a non-default flag.

What it does

same with FT-2 model & thresholds

Inputs

same

Outputs

ft2* fields

State

model file

Safeguards

SHA-256 pin; prod forbids non-default flag

Caveat prod forbids non-default flag

Intent gate with 21 frames and 9 bypass vetoes: a DENY result becomes ALLOW only when a frame matches and no bypass applies. Negators are handled, and an exception leaves the result unchanged.

What it does

frame ∧ ¬bypass → ALLOW

Inputs

DENY result + window text

Outputs

evidence, metric+log

Safeguards

bypass veto; negator handling; exception → unchanged

Generates normalisation candidates (decoded, deobfuscated, rot13; V2 adds 4 more) through evidence-gated transforms, at most 3 candidates, first DENY wins. MAX_CANDIDATES caps the cost.

What it does

evidence-gated transforms, ≤3 candidates, first DENY wins

Inputs

raw text

Safeguards

cost cap MAX_CANDIDATES

Tenant tightening of the embedding bar: an ALLOW whose score reaches the tenant bar becomes DENY. Tighten-only and clamped; the bar comes from the tenancy registry and tenant config.

What it does

ALLOW with score ≥ bar → DENY

Outputs

evidence

Depends on

tenancy registry

State

tenant config (outside scope)

Safeguards

tighten-only (clamped)

Embedding layer disable switch: when disabled the layer returns ALLOW and startup logs a warning. A guard covers the switch, and it is read from env.

What it does

disabled → ALLOW; startup warns

Inputs

env

Depends on

env

Safeguards

guard

Audits deviations from pinned defaults by diffing the effective settings against the pinned ones from env, and logs INFO or WARN so overrides stay transparent.

What it does

diff effective vs pinned

Inputs

env

Outputs

INFO/WARN logs

State

log

Safeguards

transparency of overrides

Monitors the FT-2/FT-3 consultation rate against a 0.24±0.10 band after 200 samples and then every 200, logging INFO or WARN and keeping 4 in-memory counters.

What it does

0.24±0.10 after 200 samples, every 200

Inputs

per-request results

Outputs

INFO/WARN logs, 4 counters

Depends on

metrics

State

in-memory counters

Per-tenant classification budget using token-bucket windows, charged by text length and for outputs. Over budget returns a 429-style BLOCK. State is in memory per process; it bounds DoS cost from classifiers.

What it does

token bucket windows

Inputs

tenant, text length

Outputs

429-style BLOCK; charge for outputs

State

in-memory (per process)

Safeguards

DoS bound on classifier cost

Screens non-streaming provider responses: a size cap first, then the engine, then embedding. A block is audited and the output is withheld.

What it does

size cap → engine → embedding

Inputs

provider output

Outputs

block + audit

Depends on

engine, gate

State

audit store

Safeguards

output withheld on block

Streaming incremental screening with a final recheck: inspects trailing windows of the incoming deltas with a 5 s timeout and releases output only after the check. It fails closed on timeout and returns a verdict stream.

What it does

trailing windows, 5 s timeout, release-after-check

Inputs

deltas

Outputs

verdict stream

Depends on

engine, gate, memo

Safeguards

fail-closed on timeout

Semantic screening of MCP tool results: rule findings first, then semantic and embedding checks on the tool result text. A blocked result returns TOOL_RESULT_BLOCKED_BY_POLICY.

What it does

rule findings then semantic+embedding

Inputs

tool result text

Outputs

TOOL_RESULT_BLOCKED_BY_POLICY

Depends on

engine, gate

Gives /verify parity with the main path: it runs the same functions plus a timeout over the request body and returns a BLOCK or EXECUTE prediction.

What it does

same functions + timeout

Inputs

request body

Outputs

BLOCK/EXECUTE prediction

Defines the frozen enums for the taxonomy: 14 reasons, 4 severities, 4 decisions, 4 statuses and 9 failure reasons, exported as constants.

What it does

frozen enums (14 reasons, 4 severities, 4 decisions, 4 statuses, 9 failure reasons)

Outputs

constants

Builds the semantic evidence object from the aggregate result as a frozen, audit-safe record. It holds metadata only and never the raw prompt; callers write it to the audit log.

What it does

frozen audit-safe object

Inputs

aggregate

Outputs

evidence

State

audit log (by callers)

Safeguards

no raw prompt; metadata only

Semantic env-var guard: checks env against fatal and warn lists and refuses to boot on a violation, which prevents threshold and gate drift in prod.

What it does

fatal/warn lists

Inputs

env

Outputs

boot refusal

Safeguards

prevents threshold/gate drift in prod

Real-model regression run on the real ONNX models with fixed prompts. It prints JSON lines and sets an exit code, and depends on the models.

What it does

on real ONNX

Inputs

fixed prompts

Outputs

JSON lines, exit code

Depends on

models

External held-out evaluation harness: refuses overlapping sets and computes recall and FP with Clopper-Pearson intervals from a set file, writing a result JSON. An overlap guard protects the frozen corpora.

What it does

overlap refusal, recall/FP with Clopper-Pearson

Inputs

set file

Outputs

result JSON

Depends on

frozen corpora

State

result file

Safeguards

overlap guard

Semantic measurement harness that runs the full-battery measurement on the frozen holdout and corpus. It prints a block or an optional artifact, and its inputs are hash-verified.

What it does

full-battery measurement

Inputs

frozen holdout + corpus

Outputs

printed block / optional artifact

Depends on

eval trees

State

optional artifact

Safeguards

hash-verified inputs

Real-model embedding verification scripts that check determinism, no-network, latency and equivalence against the real models, and report the outcome through an exit code.

What it does

determinism, no-network, latency, equivalence

Outputs

exit code

Depends on

models

Score-based certification evaluation: attests, verifies and scores with weights 15/10/10/5/10/15/10/10/10/5, then sets a level and critical failures. A critical-failure veto and evidence eligibility rules apply.

Maps a certification score to a level at 95, 80 and 60 and sets validity, 365 d by default. It depends on env.

What it does

≥95/80/60

Inputs

score

Outputs

level, (365 d default)

Depends on

env

Transparency registration of certifications: when the registrar rejects one (Unknown), the step logs a WARN and returns null. It depends on the registrar.

What it does

rejected by registrar (Unknown)

Inputs

result

Outputs

WARN log, =null

Depends on

registrar

Signed certificate artifact, Ed25519 and domain-separated: hashes the certification result and signs it with the active key, so it can be verified offline. Domain separation and a historical-key check protect it.

What it does

hash + sign with active key; offline verify

Inputs

certification result

Outputs

bundle

State

(PG)

Safeguards

domain separation, historical-key check

Persistence and query for certifications: PG insert and query, with recovery enqueue. Takes records, returns rows, and relies on the pg pool and PostgreSQL.

What it does

PG insert/query, recovery enqueue

Inputs

records

Outputs

rows

Depends on

pg pool

State

PostgreSQL

Webhook dispatch for certification results: sent only when a single proven tenant is identified. Tenant proof comes from attested key ids.

What it does

dispatched only if single proven tenant

Inputs

result

Outputs

webhook event

Safeguards

tenant proof from attested key ids

Batch certification service: a state machine with concurrency 5 that emits audit events and returns batch and item results. Memory store, or a file store if a dir is given; validation caps are 100/50/50.

What it does

state machine, concurrency 5, audit events

Outputs

batch + item results

Depends on

audit-log

State

memory store (file store if dir given)

Safeguards

validation caps (100/50/50)

Optional profiling endpoints for memory, GC and CPU using v8, PerformanceObserver and inspector. They return summaries only, with no heap-snapshot path, and answer 404 when disabled.

What it does

v8/PerformanceObserver/inspector

Outputs

summaries

Depends on

node internals

Safeguards

404 when disabled; summary only, no heap-snapshot path

Standalone offline profiling helpers (batch, pipeline, heap snapshot, bounded cache), described as a tool that is not wired into the tracked main tree.

What it does

Not wired in tracked main tree

Caveat Not wired in tracked main tree