Documentation
¶
Overview ¶
Package gaacceptance evaluates probe bundles collected from a customer-hosted `business-workbench` Postgres MCP deployment and produces a non-secret pass/degraded/fail acceptance report. The evaluator is pure: it consumes a pre-collected ProbeBundle (so tests can use synthetic JSON fixtures) and emits a Report plus an operator-facing Markdown summary. A separate driver (the `scripts/postgres-ga-acceptance-smoke.sh` shell wrapper, or the `gongctl mcp ga-acceptance` CLI) is responsible for assembling the bundle from a live MCP endpoint and optional Postgres reader credentials.
Index ¶
Constants ¶
const ( StatusPass = "pass" StatusDegraded = "degraded" StatusFail = "fail" )
Status values used both for the overall report and for individual checks.
const ( CheckRuntimeIdentity = "runtime_identity" CheckToolSurface = "tool_surface" CheckRoutedOperations = "routed_operations" CheckDataReadiness = "data_readiness" CheckGovernanceRedaction = "governance_redaction" CheckEvidenceWorkflow = "evidence_workflow" CheckReadOnlyPosture = "read_only_posture" )
Stable check identifiers. They are part of the operator-visible contract surfaced in the JSON report and Markdown summary.
Variables ¶
This section is empty.
Functions ¶
func RenderOperatorMarkdown ¶
RenderOperatorMarkdown formats a concise human-readable operator summary from the report. The markdown intentionally avoids emitting per-check detail blobs that may contain noisy values; it surfaces overall status, the runtime identity header, and one line per check.
Types ¶
type AccountQueryProbe ¶
type AccountQueryProbe struct {
IsError bool `json:"is_error"`
ErrorMsg string `json:"error,omitempty"`
RowCount int `json:"row_count,omitempty"`
}
AccountQueryProbe summarizes one query.calls invocation for the opt-in gate.
type CallDrilldownProbe ¶
type CallDrilldownProbe struct {
CallRef string `json:"call_ref"`
BoundedSnippetCount int `json:"bounded_snippet_count"`
GongAISourcePathCount int `json:"gong_ai_source_path_count"`
SnippetsScopedToCall bool `json:"snippets_scoped_to_call"`
Notes string `json:"notes,omitempty"`
}
CallDrilldownProbe summarizes evidence.call_drilldown for one call_ref produced by QuestionAnswer.
type Check ¶
type Check struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
Reason string `json:"reason,omitempty"`
Details map[string]any `json:"details,omitempty"`
}
Check is one named acceptance check.
type FacadeOperationProbe ¶
type FacadeOperationProbe struct {
Operation string `json:"operation"`
FacadeTool string `json:"facade_tool"`
RoutedTool string `json:"routed_tool"`
}
FacadeOperationProbe mirrors a single FacadeOperation entry surfaced by gong_discover_capabilities. Only the fields the evaluator inspects are required.
type ProbeBundle ¶
type ProbeBundle struct {
// Status is the JSON body returned by the gong_status / status.sync
// operation. Only the public mcp_server, totals, profile_readiness,
// public_readiness, attribution_coverage, call_facts_attribution
// fields are read.
Status json.RawMessage `json:"status"`
// ToolsList is the list of tool names returned by tools/list under the
// business-workbench preset.
ToolsList []string `json:"tools_list"`
// FacadeOperations is the list of routed facade operations advertised by
// gong_discover_capabilities.
FacadeOperations []FacadeOperationProbe `json:"facade_operations"`
// QuestionAnswer summarizes a synthetic question.answer call. CallRefs
// must include the call_ref later passed to evidence.call_drilldown.
QuestionAnswer *QuestionAnswerProbe `json:"question_answer,omitempty"`
// CallDrilldown summarizes the evidence.call_drilldown call that
// consumed one of QuestionAnswer.CallRefs.
CallDrilldown *CallDrilldownProbe `json:"call_drilldown,omitempty"`
// AccountQueryWithoutOptIn captures the response when calling a
// query.calls operation with account_query set but include_account_names
// omitted; it must fail closed.
AccountQueryWithoutOptIn *AccountQueryProbe `json:"account_query_without_opt_in,omitempty"`
// AccountQueryWithOptIn captures the response when calling the same
// query.calls operation with include_account_names=true; it should
// succeed (or return no rows) but not error on missing opt-in.
AccountQueryWithOptIn *AccountQueryProbe `json:"account_query_with_opt_in,omitempty"`
// RawCallIDsHidden is true when the driver verified that no raw call IDs
// (numeric Gong call IDs) appear in business-workbench tool outputs. nil
// means the driver did not check; the evaluator treats nil as degraded.
RawCallIDsHidden *bool `json:"raw_call_ids_hidden,omitempty"`
// RedactionAudit summarizes any source-minus-redacted validation evidence.
RedactionAudit *RedactionAuditProbe `json:"redaction_audit,omitempty"`
// ReadOnlyPosture summarizes the optional Postgres scoped-reader probe.
ReadOnlyPosture *ReadOnlyPostureProbe `json:"read_only_posture,omitempty"`
}
ProbeBundle is the pre-collected input for Evaluate. Each field corresponds to one MCP probe or DB probe captured by the driver. Missing optional probes are degraded checks rather than failures.
type QuestionAnswerProbe ¶
type QuestionAnswerProbe struct {
Question string `json:"question"`
EvidencePackPresent bool `json:"evidence_pack_present"`
CallRefs []string `json:"call_refs,omitempty"`
ItemCount int `json:"item_count"`
Notes string `json:"notes,omitempty"`
}
QuestionAnswerProbe summarizes the result of one synthetic question.answer call. CallRefs is the list of call_ref values returned in the evidence pack.
type ReadOnlyPostureProbe ¶
type ReadOnlyPostureProbe struct {
Provided bool `json:"provided"`
WriteDenied bool `json:"write_denied"`
WriteDenialDetail string `json:"write_denial_detail,omitempty"`
RawTableReadDenied bool `json:"raw_table_read_denied"`
RawTableReadDetail string `json:"raw_table_read_detail,omitempty"`
}
ReadOnlyPostureProbe summarizes the Postgres scoped-reader posture check. Provided=false means the operator did not supply DB URL inputs and the check is degraded (operator-supplied evidence still required for closeout).
type RedactionAuditProbe ¶
type RedactionAuditProbe struct {
Available bool `json:"available"`
SourceMinusRedactedRows int64 `json:"source_minus_redacted_rows"`
GeneratedAt string `json:"generated_at,omitempty"`
EvidencePath string `json:"evidence_path,omitempty"`
}
RedactionAuditProbe summarizes a serving-DB source-minus-redacted check. SourceMinusRedactedRows is the number of rows present in the source DB but absent from the redacted serving DB; values >0 indicate the redaction reduced the visible row set. Available=false means no audit was supplied.
type Report ¶
type Report struct {
Status string `json:"status"`
GeneratedAt string `json:"generated_at"`
Summary ReportSummary `json:"summary"`
Checks []Check `json:"checks"`
}
Report is the machine-readable evaluator output.
func Evaluate ¶
func Evaluate(b ProbeBundle) (Report, error)
Evaluate runs all required acceptance checks against the given probe bundle. It returns a Report plus an error only when the bundle is structurally invalid (e.g. unparseable status JSON). A failed check produces Report.Status=fail; degraded checks produce Report.Status=degraded; a fully-passing bundle produces Report.Status=pass.
type ReportSummary ¶
type ReportSummary struct {
DeploymentID string `json:"deployment_id,omitempty"`
Version string `json:"version,omitempty"`
Commit string `json:"commit,omitempty"`
BuildDate string `json:"build_date,omitempty"`
StartedAtUTC string `json:"started_at_utc,omitempty"`
ToolPreset string `json:"tool_preset,omitempty"`
VisibleToolCount int `json:"visible_tool_count"`
FacadeRoutedToolCount int `json:"facade_routed_tool_count"`
TranscriptEvidenceProvenance string `json:"transcript_evidence_provenance,omitempty"`
}
ReportSummary is the small operator header copied from runtime identity for quick scan in the JSON output.
Source Files