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.
list	validate_value_ownership (list records, dict families)
	Check that every capability value has an owning subsystem it does not outrank.
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
dict	DEMOTIONS = {("supported", "experimental"), ("known-defective", "planned")}
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 104 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 122 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 152 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 207 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])})"
            )
 
        reason = record.get("demotion_reason")
        if (previous, status) in DEMOTIONS:
            text = (reason or "").strip()
            if text.lower().rstrip(".") in FILLER_REASONS or len(text) < MIN_REASON_CHARS:
                problems.append(
                    f"{identifier}: {previous} -> '{status}' is a demotion and needs a "
                    f"demotion_reason saying what the earlier claim did not establish"
                )
        elif reason is not None:
            problems.append(
                f"{identifier}: demotion_reason applies only to a demotion "
                f"({sorted(DEMOTIONS)}), not {previous or 'a new record'} -> '{status}'"
            )
 
        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:

validate_value_ownership()

list audit_subsystem_lifecycle.validate_value_ownership	(	list	records,
		dict	families
	)

Check that every capability value has an owning subsystem it does not outrank.

A value's status and its subsystem's status used to be independent axes, which let a value read supported under a subsystem still experimental: the Newton-Krylov solver value, the periodic handlers, and every storage policy all did. The subsystem status is now a ceiling. The rules need the whole registry, so they are kept out of the per-record validate():

• every registered family is listed by at least one subsystem record;
• a family listed by several subsystems names each canonical value's owner in value_metadata[*].subsystem, and that owner must list the family;
• a value may not claim a ladder rung above its owner's, and under an owner that is off the ladder it must share the owner's status or be removed;
• off_switch: true exempts the single value per family that disables the owning subsystem, since selecting it claims nothing about it.

Accepted spellings and deprecated aliases inherit their target's owner and are not checked separately.

Parameters

[in]	records	Every subsystem record.
[in]	families	Capability family metadata, keyed by family id.

Returns

List of violation strings; empty means every value sits under its owner.

Definition at line 359 of file audit_subsystem_lifecycle.py.

def validate_value_ownership(records: list, families: dict) -> list:
    """!
    @brief Check that every capability value has an owning subsystem it does not outrank.
 
    @details A value's status and its subsystem's status used to be independent axes,
             which let a value read `supported` under a subsystem still `experimental`:
             the Newton-Krylov solver value, the periodic handlers, and every storage
             policy all did. The subsystem status is now a ceiling. The rules need the
             whole registry, so they are kept out of the per-record `validate()`:
 
             - every registered family is listed by at least one subsystem record;
             - a family listed by several subsystems names each canonical value's owner
               in `value_metadata[*].subsystem`, and that owner must list the family;
             - a value may not claim a ladder rung above its owner's, and under an owner
               that is off the ladder it must share the owner's status or be removed;
             - `off_switch: true` exempts the single value per family that disables
               the owning subsystem, since selecting it claims nothing about it.
 
             Accepted spellings and deprecated aliases inherit their target's owner and
             are not checked separately.
    @param[in] records Every subsystem record.
    @param[in] families Capability family metadata, keyed by family id.
    @return List of violation strings; empty means every value sits under its owner.
    """
    problems: list = []
    status_of = {record.get("id"): record.get("status") for record in records}
    listed_by: dict = {}
    for record in records:
        for family_id in record.get("capability_families", []):
            listed_by.setdefault(family_id, []).append(record.get("id"))
 
    for family_id, family in sorted(families.items()):
        owners = listed_by.get(family_id, [])
        if not owners:
            problems.append(
                f"{family_id}: no subsystem lists this family, so its values have no "
                f"lifecycle above them; add it to the owning record's capability_families"
            )
            continue
        off_switches = []
        for name, meta in sorted(family.get("value_metadata", {}).items()):
            meta = meta or {}
            if meta.get("spelling_of") or meta.get("alias_of"):
                continue
            owner = meta.get("subsystem")
            if owner is None:
                if len(owners) > 1:
                    problems.append(
                        f"{family_id}: '{name}' belongs to a family listed by {sorted(owners)}; "
                        f"name its owner in value_metadata.subsystem"
                    )
                    continue
                owner = owners[0]
            elif owner not in owners:
                problems.append(
                    f"{family_id}: '{name}' names subsystem '{owner}', which does not list "
                    f"this family"
                )
                continue
            if "off_switch" in meta:
                if meta["off_switch"] is not True:
                    problems.append(
                        f"{family_id}: '{name}' declares off_switch {meta['off_switch']!r}; "
                        f"it is either true or absent"
                    )
                off_switches.append(name)
                continue
            owner_status = status_of.get(owner)
            value_status = meta.get("status")
            if value_status in LADDER and owner_status in LADDER:
                if LADDER.index(value_status) > LADDER.index(owner_status):
                    problems.append(
                        f"{family_id}: '{name}' claims '{value_status}' but its subsystem "
                        f"'{owner}' is '{owner_status}'; a value cannot outrank the "
                        f"subsystem it belongs to"
                    )
            elif owner_status not in LADDER and value_status not in (owner_status, "removed"):
                problems.append(
                    f"{family_id}: '{name}' is '{value_status}' under '{owner}', which is "
                    f"'{owner_status}'; under an owner off the ladder a value shares its "
                    f"status or is removed"
                )
        if len(off_switches) > 1:
            problems.append(
                f"{family_id}: {off_switches} are all marked off_switch; a family has at "
                f"most one value that disables its subsystem"
            )
    return problems
 
 

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 449 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)
    problems += validate_value_ownership(records, families)
    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", "experimental", "known-defective", "deprecated"},
    "known-defective": {"known-defective", "planned", "experimental", "supported", "deprecated", "removed"},
    "deprecated": {"deprecated", "removed"},
    "removed": {"removed"},
}

Definition at line 68 of file audit_subsystem_lifecycle.py.

DEMOTIONS

dict audit_subsystem_lifecycle.DEMOTIONS = {("supported", "experimental"), ("known-defective", "planned")}

Definition at line 82 of file audit_subsystem_lifecycle.py.

VALID_VISIBILITY

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

Definition at line 84 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 87 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", "demotion_reason",
               "capability_families",
               "obligations", "concerns", "note"}

Definition at line 95 of file audit_subsystem_lifecycle.py.

MIN_REASON_CHARS

int audit_subsystem_lifecycle.MIN_REASON_CHARS = 30

Definition at line 100 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 101 of file audit_subsystem_lifecycle.py.