Response Shaping

A return block on a request chooses which parts of the response come back and how many significant digits floats carry on the wire. It exists to keep responses small for callers (agents especially) that read a fraction of them. A request with no return is byte-identical to before, hashes identically, and format_version stays "1.1".

resp, err := p.Process(ctx, &types.Request{
    // Cohort, Aggregations, ... as for any request.
    Return: &types.Return{
        Preset:    types.ReturnPresetMinimal,
        Include:   []string{"metadata.total_rows"},
        Precision: 4,
    },
})

Resolution

Preset, then include adds, then exclude removes; exclude wins. An include with no preset starts from an empty base. exclude or precision alone shape the full response. Top-level warnings and every nested warnings whose parent is emitted stay unless excluded.

Presets are full (identity), standard (data, warnings, metadata, trimmed tests and regressions, no components) and minimal (the primary result only). The manifest return_presets block lists each preset’s paths expanded against the instance.

Paths use the Response JSON names at any depth: . between keys, [*] into array elements, a trailing * on a map-key segment as a prefix glob. data[*].<column> selects output columns. The full grammar and the preset table are in Payload JSON Schema (Return slot).

What the caller sees

• An excluded part is absent on the wire, never null, and zero or nil on the Go value.
• The shaped response is a projection: it is not schema-valid against the full payload schema. Do not validate it against pulse://schema.
• A response whose plan changes something carries returned {preset, digest, precision?}. It cannot be excluded and its digest equals the one predict returns.
• precision (1 to 17 significant digits) is wire-only. Integers, decimal128 strings and NaN (null) are untouched, and counts stay exact: count-aggregation columns, count crosstab cells, and matrices[*].auxiliary.n. Extension aggregators are never exempt.

Errors

PredictResult.Return resolves and validates the block before any record is read.

Defaults and precedence

Options.DefaultReturn, else the feature profile’s return, else full, applies to every request that has no block. A request block replaces the default entirely. See pulse.New & Options and Feature Profiles.

The MCP tools add one layer on top: a request without a block is shaped by gosdk.Config.DefaultReturn / mcpserve.Options.DefaultReturn / pulse mcp --return, else the instance default above, else the built-in standard preset — never full. A request block still wins; full on the host restores the unshaped output. See pulse mcp --return.

disable_components is shorthand: alone it only skips computing components (byte-identical, no marker); with a return layer it adds exclude: ["components"]. An engine DisableComponents sticks: a request return never re-opens it, so components are not computed and the block gains exclude: ["components"]. Only an explicit request disable_components: false turns them back on.

Excluded parts are not computed

An excluded part is skipped at execution, not only on the wire: the run does less work, and a kept figure never changes. An excluded overlay layer, test or post-test runs no handler, and an excluded regressions slot fits nothing, so none raises its refusals or warnings (a rank-deficient fit, a low effective sample size); Predict still validates them. A layer, test or post-test that belongs to a multiplicity family is computed anyway, so every kept p_adjusted matches the full run. The execution path is chosen from the full request: excluding a test never moves a request onto the parallel or shard path, and a chain stage carrying tests is still refused.

Surfaces

• Process: shapes the one response.
• Compose: each slot’s return shapes responses[i]; ComposedRequest.Return shapes top-level overlays only.
• ProcessChain: each stage’s return is applied after the whole chain, so a stage that excludes data still feeds the next stage.
• Streaming: rows carry only the selected columns; returned rides the terminal chunk only; excluding data yields no rows. See Streaming & ProcessStream. A stream never raises PULSE_RETURN_PATH_UNMATCHED (it has no warnings slot); Predict lists the includes that may match nothing as return.unresolved_includes. Precision is wire-only: the library StreamChunk keeps full float64, and only the writers (api process --stream, api compose --stream) round. The MCP tools have no streaming option.

Predict size estimates

Predict reports sizes on every request, with or without a return block: per top-level section {section, full_bytes, shaped_bytes, basis} with basis one of exact, upper_bound or heuristic. Without an effective return block shaped_bytes equals full_bytes; under one, an excluded section is 0. A refused block reports no sizes, and a section whose size depends on the data is omitted rather than guessed. The figures are guidance for choosing a preset before running, not a byte-accuracy contract.