audit_subsystem_lifecycle Namespace Reference

Functions
dict	page_index ()
	Every documentation page id with the anchors it defines.
tuple	required_obligations (dict record)
	The obligation ids a record owes.
list	check_satisfaction (str context, str key, spec, dict pages, set published, bool public)
	Verify one obligation or concern is genuinely answered.
list	validate (list records, dict pages, dict families, set published)
	Validate every subsystem record against the lifecycle contract.
int	main ()
	Report subsystem lifecycle violations.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	RECORDS = REPO_ROOT / "tests" / "tooling" / "subsystem_records.json"
str	PAGE_TYPES = REPO_ROOT / "tests" / "tooling" / "page_types.json"
str	FAMILIES = REPO_ROOT / "tests" / "tooling" / "capability_families.json"
tuple	PAGE_DIRS = ("docs/pages", "docs")
tuple	LADDER = ("planned", "internal", "experimental", "supported")
dict	LADDER_OBLIGATIONS
dict	TERMINAL_OBLIGATIONS
tuple	NON_INHERITED = ("not_implemented_status",)
tuple	NEEDS_PEAK = ("known-defective", "deprecated", "removed")
tuple	INHERITS_LADDER = ("known-defective", "deprecated")
	VALID_STATUSES = tuple(LADDER) + tuple(TERMINAL_OBLIGATIONS)
dict	TRANSITIONS
tuple	VALID_VISIBILITY = ("internal", "public")
tuple	VALID_CONCERNS
dict	RECORD_KEYS
int	MIN_REASON_CHARS = 30
dict	FILLER_REASONS = {"n/a", "na", "none", "not applicable", "no", "-", "tbd"}

Detailed Description

Enforce the documentation obligations each subsystem lifecycle status carries.

Function Documentation

page_index()

dict audit_subsystem_lifecycle.page_index

(

)

Every documentation page id with the anchors it defines.

Returns

Mapping of page id to the set of @section, @subsection, and @anchor names.

Definition at line 88 of file audit_subsystem_lifecycle.py.

def page_index() -> dict:
    """!
    @brief Every documentation page id with the anchors it defines.
    @return Mapping of page id to the set of `@section`, `@subsection`, and `@anchor` names.
    """
    index: dict = {}
    for directory in PAGE_DIRS:
        for markdown in sorted((REPO_ROOT / directory).glob("*.md")):
            text = markdown.read_text(encoding="utf-8")
            match = re.search(r"^@page\s+(\S+)", text, re.M)
            if not match or match.group(1).startswith("<"):
                continue
            anchors = set(re.findall(r"^@(?:section|subsection|subsubsection|anchor)\s+(\S+)",
                                     text, re.M))
            index[match.group(1)] = anchors
    return index
 
 

Here is the caller graph for this function:

required_obligations()

tuple audit_subsystem_lifecycle.required_obligations

(

dict

record

)

The obligation ids a record owes.

A record may declare a proposed_status above its claimed one. That is how a subsystem documented to a higher bar waits for the owner to decide whether it has actually earned it: obligations are checked against the proposal, so the writing is held to the higher standard, while the status the documentation publishes stays conservative until a human agrees.

Parameters

[in]

record

One subsystem record.

Returns

Ordered tuple of obligation ids.

Definition at line 106 of file audit_subsystem_lifecycle.py.

def required_obligations(record: dict) -> tuple:
    """!
    @brief The obligation ids a record owes.
 
    @details A record may declare a `proposed_status` above its claimed one. That is
             how a subsystem documented to a higher bar waits for the owner to decide
             whether it has actually earned it: obligations are checked against the
             proposal, so the writing is held to the higher standard, while the status
             the documentation publishes stays conservative until a human agrees.
    @param[in] record One subsystem record.
    @return Ordered tuple of obligation ids.
    """
    status = record.get("proposed_status") or record.get("status")
    owed: list = []
    if status in LADDER:
        for rung in LADDER[: LADDER.index(status) + 1]:
            owed.extend(LADDER_OBLIGATIONS[rung])
    else:
        if status in INHERITS_LADDER:
            peak = record.get("peak_status")
            if peak in LADDER:
                for rung in LADDER[: LADDER.index(peak) + 1]:
                    owed.extend(LADDER_OBLIGATIONS[rung])
        owed.extend(TERMINAL_OBLIGATIONS.get(status, ()))
    if status != "planned":
        owed = [key for key in owed if key not in NON_INHERITED]
    # A status may re-owe something a lower rung already required; keep it once.
    return tuple(dict.fromkeys(owed))
 
 

Here is the caller graph for this function:

check_satisfaction()

list audit_subsystem_lifecycle.check_satisfaction	(	str	context,
		str	key,
			spec,
		dict	pages,
		set	published,
		bool	public
	)

Verify one obligation or concern is genuinely answered.

An answer is a documentation reference that resolves, or a stated reason for non-applicability, or a literal value where the obligation is a fact rather than prose. An empty or filler answer is a violation.

Parameters

[in]	context	Record id, for messages.
[in]	key	Obligation or concern id.
[in]	spec	The declared answer.
[in]	pages	Page index from page_index().
[in]	published	Ids of the pages the site publishes.
[in]	public	Whether the subsystem is publicly visible.

Returns

List of violation strings.

Definition at line 136 of file audit_subsystem_lifecycle.py.

                       public: bool) -> list:
    """!
    @brief Verify one obligation or concern is genuinely answered.
 
    @details An answer is a documentation reference that resolves, or a stated reason
             for non-applicability, or a literal value where the obligation is a fact
             rather than prose. An empty or filler answer is a violation.
    @param[in] context Record id, for messages.
    @param[in] key Obligation or concern id.
    @param[in] spec The declared answer.
    @param[in] pages Page index from page_index().
    @param[in] published Ids of the pages the site publishes.
    @param[in] public Whether the subsystem is publicly visible.
    @return List of violation strings.
    """
    if not isinstance(spec, dict):
        return [f"{context}: '{key}' must be an object, got {type(spec).__name__}"]
    problems = []
    if "not_applicable" in spec:
        reason = str(spec["not_applicable"]).strip()
        if reason.lower().rstrip(".") in FILLER_REASONS or len(reason) < MIN_REASON_CHARS:
            problems.append(
                f"{context}: '{key}' is declared not applicable without a stated reason "
                f"({reason!r}). A reasoned N/A is accepted; a bare one is not"
            )
        return problems
    if "value" in spec:
        if not str(spec["value"]).strip():
            problems.append(f"{context}: '{key}' declares an empty value")
        return problems
    page = spec.get("page")
    if not page:
        problems.append(
            f"{context}: '{key}' is unsatisfied - give it a page reference, a value, or a "
            f"reasoned not_applicable"
        )
        return problems
    if page not in pages:
        problems.append(f"{context}: '{key}' cites page '{page}', which does not exist")
        return problems
    anchor = spec.get("anchor")
    if anchor and anchor not in pages[page]:
        problems.append(
            f"{context}: '{key}' cites anchor '{anchor}' on page '{page}', which does not "
            f"define it"
        )
    if public and page not in published:
        problems.append(
            f"{context}: '{key}' cites '{page}', which is not a published page, but the "
            f"subsystem is publicly visible"
        )
    return problems
 
 

Here is the caller graph for this function:

validate()

list audit_subsystem_lifecycle.validate	(	list	records,
		dict	pages,
		dict	families,
		set	published
	)

Validate every subsystem record against the lifecycle contract.

Parameters

[in]	records	Subsystem records.
[in]	pages	Page index from page_index().
[in]	families	Capability family metadata, keyed by family id.
[in]	published	Ids of the pages the site publishes.

Returns

List of violation strings; empty means the contract holds.

Definition at line 191 of file audit_subsystem_lifecycle.py.

def validate(records: list, pages: dict, families: dict, published: set) -> list:
    """!
    @brief Validate every subsystem record against the lifecycle contract.
    @param[in] records Subsystem records.
    @param[in] pages Page index from page_index().
    @param[in] families Capability family metadata, keyed by family id.
    @param[in] published Ids of the pages the site publishes.
    @return List of violation strings; empty means the contract holds.
    """
    problems: list = []
    seen: set = set()
    for record in records:
        identifier = record.get("id")
        if not identifier:
            problems.append("a record declares no id")
            continue
        if identifier in seen:
            problems.append(f"{identifier}: declared more than once")
        seen.add(identifier)
 
        unknown = set(record) - RECORD_KEYS
        if unknown:
            problems.append(f"{identifier}: unknown field(s) {sorted(unknown)}")
 
        status = record.get("status")
        if status not in VALID_STATUSES:
            problems.append(
                f"{identifier}: status {status!r} is not one of {list(VALID_STATUSES)}"
            )
            continue
 
        visibility = record.get("visibility")
        if visibility not in VALID_VISIBILITY:
            problems.append(
                f"{identifier}: visibility {visibility!r} is not one of "
                f"{list(VALID_VISIBILITY)}"
            )
            continue
        if status == "internal" and visibility != "internal":
            problems.append(
                f"{identifier}: status 'internal' contradicts visibility 'public'; a "
                f"subsystem the user can reach is at least experimental"
            )
 
        previous = record.get("previous_status", None)
        if previous is not None and previous not in VALID_STATUSES:
            problems.append(f"{identifier}: previous_status {previous!r} is not a valid status")
        elif status not in TRANSITIONS[previous]:
            problems.append(
                f"{identifier}: {previous or 'a new record'} -> '{status}' is not a valid "
                f"lifecycle transition (allowed: {sorted(TRANSITIONS[previous])})"
            )
 
        proposed = record.get("proposed_status")
        if proposed is not None:
            if proposed not in LADDER:
                problems.append(
                    f"{identifier}: proposed_status {proposed!r} must name a rung of "
                    f"{list(LADDER)}"
                )
            elif status not in LADDER or LADDER.index(proposed) <= LADDER.index(status):
                problems.append(
                    f"{identifier}: proposed_status '{proposed}' is not above the claimed "
                    f"status '{status}'; a proposal that is not a promotion is noise"
                )
            elif not record.get("promotion_rationale"):
                problems.append(
                    f"{identifier}: proposes '{proposed}' but gives no promotion_rationale. "
                    f"Say what the owner is being asked to confirm"
                )
 
        if status in NEEDS_PEAK:
            peak = record.get("peak_status")
            if peak not in LADDER:
                problems.append(
                    f"{identifier}: status '{status}' requires peak_status naming the highest "
                    f"rung it reached, one of {list(LADDER)}"
                )
        elif record.get("peak_status") is not None:
            problems.append(
                f"{identifier}: peak_status applies only to {list(NEEDS_PEAK)}, not '{status}'"
            )
 
        obligations = record.get("obligations") or {}
        owed = required_obligations(record)
        for key in owed:
            if key not in obligations:
                problems.append(
                    f"{identifier}: status '{status}' owes '{key}', which is not declared"
                )
            else:
                problems.extend(
                    check_satisfaction(identifier, key, obligations[key], pages, published,
                                       visibility == "public")
                )
        for key in sorted(set(obligations) - set(owed)):
            problems.append(
                f"{identifier}: declares obligation '{key}', which status '{status}' does not "
                f"owe; remove it or claim the status that owes it"
            )
 
        concerns = record.get("concerns") or {}
        for key in sorted(concerns):
            if key not in VALID_CONCERNS:
                problems.append(
                    f"{identifier}: concern '{key}' is not in the concern vocabulary of "
                    f"64_Documentation_Extension_Framework"
                )
                continue
            problems.extend(
                check_satisfaction(identifier, key, concerns[key], pages, published,
                                   visibility == "public")
            )
 
        # A planned subsystem must not already be presented as working behavior.
        for family_id in record.get("capability_families", []):
            family = families.get(family_id)
            if family is None:
                problems.append(
                    f"{identifier}: cites capability family '{family_id}', which is not "
                    f"registered"
                )
                continue
            if status != "planned":
                continue
            live = sorted(
                name for name, meta in family.get("value_metadata", {}).items()
                if (meta or {}).get("status") == "supported"
            )
            if live:
                problems.append(
                    f"{identifier}: is 'planned' but family '{family_id}' already offers "
                    f"supported value(s) {live}; a planned subsystem must not appear as "
                    f"supported behavior"
                )
    return problems
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

main()

int audit_subsystem_lifecycle.main

(

)

Report subsystem lifecycle violations.

Returns

Process status code.

Definition at line 329 of file audit_subsystem_lifecycle.py.

def main() -> int:
    """!
    @brief Report subsystem lifecycle violations.
    @return Process status code.
    """
    document = json.loads(RECORDS.read_text(encoding="utf-8"))
    records = document["subsystems"]
    published = set(json.loads(PAGE_TYPES.read_text(encoding="utf-8"))["assignments"])
    families = {
        family["id"]: family
        for family in json.loads(FAMILIES.read_text(encoding="utf-8"))["families"]
    }
    problems = validate(records, page_index(), families, published)
    if problems:
        print("Subsystem lifecycle violations:", file=sys.stderr)
        for problem in problems:
            print(f"  {problem}", file=sys.stderr)
        print(
            "\nObligations grow with the status a subsystem claims. See\n"
            "64_Documentation_Extension_Framework section 4. Lower the claimed status, or\n"
            "write the documentation that status owes - do not add empty prose to pass.",
            file=sys.stderr,
        )
        return 1
 
    from collections import Counter
    spread = Counter(record["status"] for record in records)
    summary = ", ".join(f"{count} {status}" for status, count in sorted(spread.items()))
    print(f"Subsystem lifecycle audit passed: {len(records)} subsystem(s) ({summary}).")
    proposals = [r for r in records if r.get("proposed_status")]
    if proposals:
        print(f"\n{len(proposals)} promotion(s) awaiting the owner's decision. The "
              f"documentation meets the higher bar; whether the subsystem has earned "
              f"the status is a human judgement this gate cannot make:")
        for record in proposals:
            print(f"  {record['id']}: {record['status']} -> {record['proposed_status']}")
            print(f"      {record['promotion_rationale']}")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

audit_subsystem_lifecycle.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 12 of file audit_subsystem_lifecycle.py.

RECORDS

str audit_subsystem_lifecycle.RECORDS = REPO_ROOT / "tests" / "tooling" / "subsystem_records.json"

Definition at line 13 of file audit_subsystem_lifecycle.py.

PAGE_TYPES

str audit_subsystem_lifecycle.PAGE_TYPES = REPO_ROOT / "tests" / "tooling" / "page_types.json"

Definition at line 14 of file audit_subsystem_lifecycle.py.

FAMILIES

str audit_subsystem_lifecycle.FAMILIES = REPO_ROOT / "tests" / "tooling" / "capability_families.json"

Definition at line 15 of file audit_subsystem_lifecycle.py.

PAGE_DIRS

tuple audit_subsystem_lifecycle.PAGE_DIRS = ("docs/pages", "docs")

Definition at line 16 of file audit_subsystem_lifecycle.py.

LADDER

tuple audit_subsystem_lifecycle.LADDER = ("planned", "internal", "experimental", "supported")

Definition at line 21 of file audit_subsystem_lifecycle.py.

LADDER_OBLIGATIONS

dict audit_subsystem_lifecycle.LADDER_OBLIGATIONS

Initial value:

=  {
    "planned": ("purpose", "intended_scope", "design_owner", "not_implemented_status"),
    "internal": ("scope_boundary", "architecture_boundary", "dependencies",
                 "developer_entry_points"),
    "experimental": ("configuration", "selection_guidance", "observability", "limitations",
                     "safe_use_boundaries"),
    "supported": ("evidence", "lifecycle_and_restart", "operations", "troubleshooting",
                  "examples", "complete_reference"),
}

Definition at line 23 of file audit_subsystem_lifecycle.py.

TERMINAL_OBLIGATIONS

dict audit_subsystem_lifecycle.TERMINAL_OBLIGATIONS

Initial value:

=  {
    "known-defective": ("defect_disclosure", "defect_scope_record", "safe_use_boundaries",
                        "limitations"),
    "deprecated": ("migration_path", "replacement", "compatibility_period", "removal_policy"),
    "removed": ("history_record", "rejection_behavior"),
}

Definition at line 35 of file audit_subsystem_lifecycle.py.

NON_INHERITED

tuple audit_subsystem_lifecycle.NON_INHERITED = ("not_implemented_status",)

Definition at line 43 of file audit_subsystem_lifecycle.py.

NEEDS_PEAK

tuple audit_subsystem_lifecycle.NEEDS_PEAK = ("known-defective", "deprecated", "removed")

Definition at line 44 of file audit_subsystem_lifecycle.py.

INHERITS_LADDER

tuple audit_subsystem_lifecycle.INHERITS_LADDER = ("known-defective", "deprecated")

Definition at line 46 of file audit_subsystem_lifecycle.py.

VALID_STATUSES

audit_subsystem_lifecycle.VALID_STATUSES = tuple(LADDER) + tuple(TERMINAL_OBLIGATIONS)

Definition at line 48 of file audit_subsystem_lifecycle.py.

TRANSITIONS

dict audit_subsystem_lifecycle.TRANSITIONS

Initial value:

=  {
    None: set(VALID_STATUSES) - {"removed"},
    "planned": {"planned", "internal", "experimental", "supported", "removed"},
    "internal": {"internal", "experimental", "supported", "known-defective", "deprecated"},
    "experimental": {"experimental", "supported", "known-defective", "deprecated"},
    "supported": {"supported", "known-defective", "deprecated"},
    "known-defective": {"known-defective", "experimental", "supported", "deprecated", "removed"},
    "deprecated": {"deprecated", "removed"},
    "removed": {"removed"},
}

Definition at line 58 of file audit_subsystem_lifecycle.py.

VALID_VISIBILITY

tuple audit_subsystem_lifecycle.VALID_VISIBILITY = ("internal", "public")

Definition at line 69 of file audit_subsystem_lifecycle.py.

VALID_CONCERNS

tuple audit_subsystem_lifecycle.VALID_CONCERNS

Initial value:

=  (
    "numerical_method", "user_selector", "units_and_nondimensionalization",
    "artifact_topology", "persistent_restart_state", "determinism_and_reproducibility",
    "mpi_distributed_execution", "external_service", "security_credentials",
    "generated_artifact", "file_format", "destructive_scope", "backward_compatibility",
    "scientific_verification",
)

Definition at line 72 of file audit_subsystem_lifecycle.py.

RECORD_KEYS

dict audit_subsystem_lifecycle.RECORD_KEYS

Initial value:

=  {"id", "title", "status", "visibility", "previous_status", "peak_status",
               "proposed_status", "promotion_rationale", "capability_families",
               "obligations", "concerns", "note"}

Definition at line 80 of file audit_subsystem_lifecycle.py.

MIN_REASON_CHARS

int audit_subsystem_lifecycle.MIN_REASON_CHARS = 30

Definition at line 84 of file audit_subsystem_lifecycle.py.

FILLER_REASONS

dict audit_subsystem_lifecycle.FILLER_REASONS = {"n/a", "na", "none", "not applicable", "no", "-", "tbd"}

Definition at line 85 of file audit_subsystem_lifecycle.py.