Suites

pghf.add_check_to_run(p_run_key text, p_check_id text, p_position integer DEFAULT NULL)

Adds (or repositions) one check within a named suite.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Must reference an active suite.
p_check_id	text	Yes	—	Must reference a non-retired check.
p_position	integer	No	empty = append to the end	An explicit 1-based position; later members shift down to make room.

Returns: nothing. Raises an error if the check's namespace or category has been inactivated. Only a role explicitly granted permission can call this.

pghf.add_checks_matching(p_run_key text, p_pattern text, p_show_only boolean DEFAULT true)

Bulk-adds checks by pattern matched against their check ID — either an exact match, or a right-anchored wildcard like 'PGHF01-*' (the * is only allowed as the final character). Preview-by-default: leaving p_show_only at its default of true returns what would be added without touching anything, and never errors on zero matches; only passing p_show_only => false actually performs the add — and that path raises an error if the pattern matches nothing at all.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Target suite (only resolved and validated when actually adding).
p_pattern	text	Yes	—	An exact check ID, or a prefix ending in a single trailing *.
p_show_only	boolean	No	true	true = preview only (safe, changes nothing). false = actually add the matches, raising an error on zero matches or on the first match whose namespace/category has been inactivated.

Returns: one row per matched check, whether previewing or actually adding, including a column flagging whether that check's namespace/category is currently inactive (which would make a real add fail). Only a role explicitly granted permission can call this.

pghf.add_checks_to_run(p_run_key text, VARIADIC p_check_ids text[])

Bulk-append version of pghf.add_check_to_run(): appends every given check ID, in the order given, to the end of the suite.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Target suite.
p_check_ids	text[] (variadic)	Yes	—	One or more check IDs, e.g. ('default', 'X01-001', 'X01-002').

Returns: nothing. Only a role explicitly granted permission can call this.

pghf.create_check_run(p_run_key text, p_description text DEFAULT NULL, p_is_active boolean DEFAULT true)

The only way to define, redescribe, or activate/inactivate a named suite — a genuine upsert keyed on the suite's name; calling it again for an existing name updates its description and active state rather than failing.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Short human name, e.g. 'default'. The natural key this upserts on.
p_description	text	No	empty	Free-text description.
p_is_active	boolean	No	true	false inactivates the suite (history untouched; existing member checks are unaffected).

Returns: uuid — the suite's internal identifier. Only a role explicitly granted permission can call this.

pghf.get_check_run(p_run_key text)

Returns one suite record by name.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Suite to look up.

Returns: the suite record. Raises an error if not found.

pghf.list_check_run_members(p_run_key text)

Lists one suite's membership in order, resolved to human-readable check identity.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Suite to list membership for. Must exist.

Returns: one row per member, in order, including its position, check ID, check name, and category. Raises an error if the suite doesn't exist.

pghf.list_check_runs(p_only_active boolean DEFAULT NULL)

Lists suite records.

Parameter	Type	Mandatory	Default	Description
p_only_active	boolean	No	empty = no filter	true = active only, false = inactive only.

Returns: zero or more suite records, ordered by suite name.

pghf.remove_check_from_run(p_run_key text, p_check_id text)

Removes one member from a suite, without affecting any other member's position. A check can always be pulled out of a suite regardless of catalog state.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Suite to remove from. Must exist.
p_check_id	text	Yes	—	Check to remove. Must exist.

Returns: nothing. Only a role explicitly granted permission can call this.

pghf.remove_checks_from_run(p_run_key text, VARIADIC p_check_ids text[])

Bulk-remove version of pghf.remove_check_from_run(): removes every given check ID, in order, with the same per-item checks.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	Yes	—	Suite to remove from.
p_check_ids	text[] (variadic)	Yes	—	One or more check IDs to remove.

Returns: nothing. Only a role explicitly granted permission can call this.

Continue to Check Implementation Functions.