Documentation
¶
Overview ¶
Package projection implements the response projection engine: field allowlist filtering, byte-budget truncation on word boundaries, _nexus metadata injection, and metadata stripping.
Reference: Tech Spec Section 7.2, Section 9.3, Phase 2.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodedSize ¶
EncodedSize returns the byte length of the JSON encoding of v. It uses a pooled buffer to avoid allocations on the hot path.
func FitBudget ¶
FitBudget applies the byte-budget constraint to a slice of projected record maps. It measures the serialized JSON size of the full records slice; if that size exceeds maxBytes it truncates the "content" field of each record on word boundaries (last record first) until the response fits.
maxBytes <= 0 disables the budget check (no truncation).
Returns the (possibly mutated) records slice and a boolean that is true when any truncation occurred. The input slice is modified in place; callers that need the originals must copy before calling.
Reference: Tech Spec Section 9.3 (max_response_bytes), Phase 2 Behavioral Contract item 2.
func TruncateOnWordBoundary ¶
TruncateOnWordBoundary shortens s so that its UTF-8 byte length does not exceed maxBytes. Truncation always ends on a word boundary:
- If the byte at position maxBytes is a space (i.e. the cut already falls between two words), the preceding word is returned intact.
- Otherwise the last space before maxBytes is found and the string is truncated there.
- If no space exists before the cut, the string is truncated at the rune-safe cut point (never inside a multi-byte sequence).
Returns the (possibly shortened) string and a boolean that is true when truncation occurred. If maxBytes <= 0, the empty string is returned with truncated = (len(s) > 0).
Reference: Tech Spec Section 9.3, Phase 2 Behavioral Contract item 2.
Types ¶
type NexusMetadata ¶
type NexusMetadata struct {
// Stage names the retrieval stage that produced the result set.
// Examples: "structured", "exact_cache", "fast_path", "semantic".
Stage string `json:"stage"`
// unreachable and Stages 2+4 were skipped.
SemanticUnavailable bool `json:"semantic_unavailable"`
// Omitted when SemanticUnavailable is false.
SemanticUnavailableReason string `json:"semantic_unavailable_reason,omitempty"`
// ResultCount is the number of records returned in this response page.
ResultCount int `json:"result_count"`
// Truncated is true when one or more content fields were shortened to
// satisfy the policy max_response_bytes budget.
Truncated bool `json:"truncated"`
// NextCursor is the opaque base64 cursor for the next result page.
// Omitted when HasMore is false.
NextCursor string `json:"next_cursor,omitempty"`
// HasMore indicates that additional result pages are available.
HasMore bool `json:"has_more"`
// TemporalDecayApplied is true when temporal decay reranking was applied
// to the result set (Phase 6+).
TemporalDecayApplied bool `json:"temporal_decay_applied"`
// TemporalDecayMode is "exponential" or "step". Omitted when
// TemporalDecayApplied is false.
TemporalDecayMode string `json:"temporal_decay_mode,omitempty"`
// ConsistencyScore is a 0.0–1.0 measure of write-to-read consistency for
// the returned records. 0.0 means unverified; 1.0 means fully consistent.
ConsistencyScore float64 `json:"consistency_score"`
// Profile is the retrieval profile used: "fast", "balanced", or "deep".
Profile string `json:"profile"`
}
NexusMetadata is the _nexus block appended to every query response. It carries pipeline diagnostics for the client without exposing internal routing details.
Reference: Tech Spec Section 7.2.
type Response ¶
type Response struct {
Records []map[string]any `json:"records"`
Nexus *NexusMetadata `json:"_nexus,omitempty"`
}
Response is the final JSON-serializable query response. It contains the projected record maps and, when strip_metadata is false, the _nexus block.
Records is a slice of maps rather than typed structs so that the field allowlist can be applied by key exclusion without reflection on every call.
func Apply ¶
func Apply( records []destination.TranslatedPayload, pol policy.PolicyEntry, meta NexusMetadata, ) Response
Apply projects records through the policy field allowlist, enforces the byte budget, and assembles the final Response with optional _nexus metadata.
Steps:
- Each TranslatedPayload is converted to a map[string]any keyed by JSON tag name.
- The policy field_visibility.include_fields allowlist is applied; unlisted fields are dropped. An empty allowlist retains all fields.
- The "content" fields are truncated on word boundaries if the serialized records exceed pol.MaxResponseBytes (0 = unlimited).
- meta.Truncated is set to true if any truncation occurred.
- meta.ResultCount is set to len(records).
- If pol.FieldVisibility.StripMetadata is true the _nexus block is omitted from the response. Otherwise it is included.
Reference: Tech Spec Section 9.3, Phase 2 Behavioral Contract items 1–4.
Source Files