Prompt Engineering

Six-stage pipeline

A prompt is never built on the spot. Six stages collect, organise and verify every fact around the request before anything reaches the LLM. Each stage lives in its own package and the output of one stage is the input of the next.

Stage 1 · Collect

Once a request enters the Spring Security filter chain, an AuthBridge implementation pulls the principal out of headers, session attributes or request attributes. The extracted evidence is packaged into three kinds of evidence stamps. Those three stamps are the raw input for every later stage.

Five evidence quality tiers

Not all evidence carries the same weight. A signal the customer sent explicitly is the strongest; a platform-observed structural signal comes next; a fallback derived from runtime continuity is the weakest. BridgeSemanticBoundaryPolicy tags every collected field with one of the tiers below.

Stage 2 · Process

Raw evidence alone is not enough for the LLM to decide whether a user is acting differently from usual. Stage 2 expands it through three families of components that turn primitive facts into observable patterns.

Stage 3 · Harden

Prompt injection, field spoofing and signal forgery are the top threats for any LLM-based security system. CanonicalSecurityContextHardener puts every field through field-specific normalisation before it ever reaches the model.

Stage 4 · Standardise

After stage 3, every piece of evidence is consolidated into a single standard context model — CanonicalSecurityContext. The current implementation is a Lombok-backed class; the hardener normalizes fields and fills required defaults before the compose stage receives it. Twenty-two fields and seven profiles sit in well-known places, so the compose stage always knows where each field lives.

Four coverage levels

ContextCoverageEvaluator grades how complete the record is by counting filled fields and available profiles. A low grade automatically injects a warning into the prompt telling the LLM not to draw strong conclusions from "usual work patterns".

Stage 5 · Compose

The standardised context now becomes a prompt. SecurityDecisionPromptSections orchestrates the work and renders 2 system sections plus 15 user sections, for 17 section plans in total. When a field is missing, the builder for that section simply emits nothing.

System side and user side

17 section plans

EXPLICIT_MISSING_KNOWLEDGE

EXPLICIT_MISSING_KNOWLEDGE is a P0 required quality indicator section that prevents the LLM from mistaking evidence gaps for certainty. SecurityContextQualityUserSectionBuilder calls PromptContextComposer.composeMissingKnowledgeSection() and renders the section only when coverage gaps or trust-profile evidence cautions exist. If no gap signal exists, the section remains empty; that means there is no explicit missing knowledge to declare.

• Coverage gaps — missingCriticalFacts, remediationHints, or confidenceWarnings create the missing-knowledge section.
• Trust limits — ContextEvidenceLimitation, ContextTrustLimitation, ContextTrustWarning, ContextFieldCoverage, and ContextFieldLimitation are surfaced as explicit items.
• False-positive control — stale AUTHORIZATION_EFFECT missing-context warnings are suppressed once the authorization effect has been resolved.
• Baseline support — sparse personal or organisational baselines add BaselineGapSupport to remind the model that missing evidence is not proof of either risk or legitimacy.
• Compression preservation — compact budgets prioritise BaselineGapSupport, ConfidenceWarning, ContextEvidenceLimitation, ContextTrustLimitation, and ContextTrustWarning. If the budget still overflows, summarised or omitted details are recorded in the compression ledger.

Stage 6 · Calibrate

Getting a response back from the LLM is not the end. Two safety layers adjust the result in sequence: the autonomy guardrail and the runtime calibration.

Autonomy guardrail

If the LLM's confidence is below a threshold or the output deviates from the schema, PromptConfidenceGuardrail forces the final action up to a safer tier. The proposed action and the enforced action are stored separately to keep the audit trail intact.

Runtime calibration

Decisions the guardrail did not touch are fine-tuned by SecurityDecisionCalibrationService using learned profiles. Confidence adjustments and action biases are applied based on past observations.

• Scenario classification — group the current request with past similar scenarios (for example, unfamiliar location + unusual resource)
• Profile selection — pick only profiles that have enough samples and operator review
• Action bias — one of INCREASE_CHALLENGE · DECREASE_CHALLENGE · NONE
• BLOCK is immutable — a BLOCK decision is never changed by a bias (safety first)
• Guardrail wins — if the guardrail already intervened, calibration is skipped

The final decision record

What comes out the other end is the SecurityDecision. It is not just "ALLOW" or "BLOCK". It is an auditable record that carries the LLM's raw judgement, the policy intervention, and the learning calibration — all three.

How prompts differ for humans and agents

The pipeline is the same, but the centre of gravity shifts depending on who the subject is. For a human, the key axis is "deviation from the usual pattern". For an agent, it is "staying within the allowed objective".

Related documentation