api581-engine 0.1.4__py3-none-any.whl

api581/standard.py

@@ -0,0 +1,281 @@
+"""Read-only API 581 Part 1 standard metadata.
+
+The metadata is extracted from the supplied 2016 PDF during the source-data
+build and packaged as JSON.  These helpers are deliberately documentary: they
+do not infer applicability, replace engineering qualification, or act as
+calculation inputs.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from .core import Model, ensure
+
+__all__ = [
+    "StandardDefinition", "StandardAcronym", "StandardReference", "StandardSection", "SupportingTextLocator", "SupportingTextReview", "DocumentaryCoverage", "standard_metadata",
+    "definitions", "definition", "acronyms", "acronym",
+    "references", "reference", "sections", "section", "supporting_text_review", "documentary_coverage",
+]
+
+
+class StandardDefinition(Model):
+    model_config = ConfigDict(frozen=True)
+    clause: str = Field(min_length=1)
+    term: str = Field(min_length=1)
+    acronym: str | None = None
+    definition: str = Field(min_length=1)
+    source_page: int = Field(gt=0)
+
+
+class StandardAcronym(Model):
+    model_config = ConfigDict(frozen=True)
+    acronym: str = Field(min_length=1)
+    expansion: str = Field(min_length=1)
+    source_page: int = Field(gt=0)
+
+
+class StandardReference(Model):
+    model_config = ConfigDict(frozen=True)
+    category: str = Field(pattern=r"^(normative|informative)$")
+    number: int = Field(gt=0)
+    citation: str = Field(min_length=1)
+    source_page: int = Field(gt=0)
+
+
+class StandardSection(Model):
+    """Typed view of one source-heading ledger entry."""
+    model_config = ConfigDict(extra="ignore", frozen=True)
+    id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    status: str = Field(pattern=r"^(partial|not_implemented)$")
+    review_category: str = Field(pattern=r"^(technical_scope_review|supporting_text_review)$")
+    scope: str = Field(min_length=1)
+    calculation_ids: tuple[str, ...] = ()
+    next_evidence_needed: str = Field(min_length=1)
+
+
+class SupportingTextLocator(Model):
+    """Immutable source locator and extracted-page fingerprint."""
+    model_config = ConfigDict(extra="ignore", frozen=True)
+    pdf: str = Field(min_length=1)
+    toc_pdf_page: int | None = Field(default=None, ge=1)
+    printed_page_in_part: str | None = None
+    extracted_page_text_sha256: str = Field(min_length=64, max_length=64)
+    extracted_page_text_bytes: int = Field(ge=0)
+
+
+class SupportingTextReview(Model):
+    """Typed provenance record for a non-calculational source heading."""
+    model_config = ConfigDict(extra="ignore", frozen=True)
+    clause_id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    scope: str = Field(min_length=1)
+    source_locator: SupportingTextLocator
+    review_category: str = Field(pattern=r"^(technical_scope_review|supporting_text_review)$")
+    classification: str = Field(min_length=1)
+    evidence_target: str = Field(min_length=1)
+    next_action: str = Field(min_length=1)
+    calculation_ids: tuple[str, ...] = ()
+
+
+class DocumentaryCoverage(Model):
+    """Typed documentary-evidence boundary for the source heading ledger."""
+    model_config = ConfigDict(frozen=True)
+    standard_edition: str = Field(min_length=1)
+    source_sha256: str = Field(min_length=64, max_length=64)
+    metadata_sources: dict[str, str]
+    metadata_covered_section_ids: tuple[str, ...]
+    metadata_covered_count: int = Field(ge=0)
+    supporting_review_section_ids: tuple[str, ...]
+    supporting_review_count: int = Field(ge=0)
+    unimplemented_supporting_section_ids: tuple[str, ...]
+    unimplemented_supporting_count: int = Field(ge=0)
+
+
+@lru_cache(maxsize=1)
+def _metadata() -> dict[str, Any]:
+    resource = files("api581").joinpath("data/standard-metadata.json")
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def standard_metadata() -> dict[str, str | int]:
+    """Return edition and source identifiers without exposing mutable tables."""
+    payload = _metadata()
+    coverage = json.loads(files("api581").joinpath("data/coverage.json").read_text(encoding="utf-8"))
+    return {"standard_edition": payload["standard_edition"], "source": payload["source"],
+            "source_sha256": payload["source_sha256"],
+            "definition_count": len(payload["definitions"]), "acronym_count": len(payload["acronyms"]),
+            "reference_count": len(payload["references"]), "section_count": len(coverage["sections"])}
+
+
+@lru_cache(maxsize=1)
+def _definitions() -> tuple[StandardDefinition, ...]:
+    return tuple(StandardDefinition.model_validate(item) for item in _metadata()["definitions"])
+
+
+@lru_cache(maxsize=1)
+def _acronyms() -> tuple[StandardAcronym, ...]:
+    return tuple(StandardAcronym.model_validate(item) for item in _metadata()["acronyms"])
+
+
+@lru_cache(maxsize=1)
+def _references() -> tuple[StandardReference, ...]:
+    return tuple(StandardReference.model_validate(item) for item in _metadata()["references"])
+
+
+@lru_cache(maxsize=1)
+def _sections() -> tuple[StandardSection, ...]:
+    resource = files("api581").joinpath("data/coverage.json")
+    payload = json.loads(resource.read_text(encoding="utf-8"))
+    normalized = []
+    for item in payload["sections"]:
+        row = dict(item)
+        row["scope"] = row["id"].split(" §", 1)[0]
+        normalized.append(row)
+    return tuple(StandardSection.model_validate(item) for item in normalized)
+
+
+@lru_cache(maxsize=1)
+def _supporting_text_reviews() -> tuple[SupportingTextReview, ...]:
+    resource = files("api581").joinpath("data/supporting-text-review.json")
+    payload = json.loads(resource.read_text(encoding="utf-8"))
+    return tuple(SupportingTextReview.model_validate(item) for item in payload["clauses"])
+
+
+def definitions(query: str | None = None) -> tuple[StandardDefinition, ...]:
+    """List definitions, optionally matching term, acronym, clause, or text."""
+    items = _definitions()
+    if query is None:
+        return items
+    needle = query.strip().casefold()
+    ensure(needle, "query must not be blank", "invalid_standard_query")
+    return tuple(item for item in items if needle in " ".join(
+        value for value in (item.term, item.acronym or "", item.clause, item.definition)
+    ).casefold())
+
+
+def definition(term_or_clause: str) -> StandardDefinition:
+    """Return one exact definition or raise a typed documentary error."""
+    needle = term_or_clause.strip().casefold()
+    ensure(needle, "term_or_clause must not be blank", "invalid_standard_query")
+    matches = tuple(item for item in _definitions()
+                    if item.term.casefold() == needle or item.clause.casefold() == needle)
+    ensure(len(matches) == 1, "No unique API 581 definition matched the query", "standard_definition_not_found")
+    return matches[0]
+
+
+def acronyms(prefix: str | None = None) -> tuple[StandardAcronym, ...]:
+    """List acronyms, optionally by case-insensitive prefix."""
+    items = _acronyms()
+    if prefix is None:
+        return items
+    needle = prefix.strip().casefold()
+    ensure(needle, "prefix must not be blank", "invalid_standard_query")
+    return tuple(item for item in items if item.acronym.casefold().startswith(needle))
+
+
+def acronym(key: str) -> StandardAcronym:
+    """Return one exact acronym expansion or raise a typed documentary error."""
+    needle = key.strip().casefold()
+    ensure(needle, "key must not be blank", "invalid_standard_query")
+    matches = tuple(item for item in _acronyms() if item.acronym.casefold() == needle)
+    ensure(len(matches) == 1, "No unique API 581 acronym matched the query", "standard_acronym_not_found")
+    return matches[0]
+
+
+def references(category: str | None = None) -> tuple[StandardReference, ...]:
+    """List Part 1 §2 references, optionally filtered by category."""
+    items = _references()
+    if category is None:
+        return items
+    needle = category.strip().casefold()
+    ensure(needle in {"normative", "informative"},
+           "category must be normative or informative", "invalid_standard_query")
+    return tuple(item for item in items if item.category == needle)
+
+
+def reference(number: int, *, category: str = "informative") -> StandardReference:
+    """Return one Part 1 §2 reference by category and source number."""
+    matches = tuple(item for item in references(category) if item.number == number)
+    ensure(len(matches) == 1, "No unique API 581 reference matched the query", "standard_reference_not_found")
+    return matches[0]
+
+
+def sections(*, status: str | None = None, review_category: str | None = None,
+             scope: str | None = None) -> tuple[StandardSection, ...]:
+    """List source headings from the packaged coverage ledger with filters."""
+    if status is not None:
+        ensure(status in {"partial", "not_implemented"},
+               "status must be partial or not_implemented", "invalid_standard_query")
+    if review_category is not None:
+        ensure(review_category in {"technical_scope_review", "supporting_text_review"},
+               "review_category is not recognized", "invalid_standard_query")
+    if scope is not None:
+        ensure(isinstance(scope, str) and bool(scope.strip()),
+               "scope must be a non-empty string or None", "invalid_standard_query")
+    return tuple(item for item in _sections()
+                 if (status is None or item.status == status)
+                 and (review_category is None or item.review_category == review_category)
+                 and (scope is None or item.scope.casefold() == scope.strip().casefold()))
+
+
+def section(section_id: str) -> StandardSection:
+    """Return one source heading and its next evidence requirement."""
+    needle = section_id.strip().casefold()
+    ensure(needle, "section_id must not be blank", "invalid_standard_query")
+    matches = tuple(item for item in _sections() if item.id.casefold() == needle)
+    ensure(len(matches) == 1, "No unique API 581 source section matched the query", "standard_section_not_found")
+    return matches[0]
+
+
+def supporting_text_review(clause_id: str | None = None) -> tuple[SupportingTextReview, ...]:
+    """Return source-locator and evidence-routing records for supporting headings."""
+    items = _supporting_text_reviews()
+    if clause_id is None:
+        return items
+    needle = clause_id.strip().casefold()
+    ensure(needle, "clause_id must not be blank", "invalid_standard_query")
+    matches = tuple(item for item in items if item.clause_id.casefold() == needle)
+    ensure(matches, "No supporting-text review matched the clause", "standard_section_not_found")
+    return matches
+
+
+def documentary_coverage() -> DocumentaryCoverage:
+    """Summarize source headings covered by extracted documentary metadata.
+
+    Part 1 §2 (references) and Part 1 §3 (definitions/acronyms) are not
+    numerical calculation clauses, but their source data is packaged and
+    queryable through this module.  The remaining supporting-text headings
+    stay explicitly listed so metadata extraction is not mistaken for full
+    clause interpretation.
+    """
+    source_sections = _sections()
+    metadata_prefixes = ("Part 1 §2", "Part 1 §3")
+    covered = tuple(item.id for item in source_sections
+                    if item.id.startswith(metadata_prefixes))
+    supporting_review = tuple(item.id for item in source_sections
+                              if item.review_category == "supporting_text_review"
+                              and item.id not in covered)
+    unimplemented = tuple(item.id for item in source_sections
+                          if item.status == "not_implemented")
+    metadata = standard_metadata()
+    return DocumentaryCoverage.model_validate({
+        "standard_edition": metadata["standard_edition"],
+        "source_sha256": metadata["source_sha256"],
+        "metadata_sources": {
+            "references": "standard-metadata.json:references",
+            "definitions": "standard-metadata.json:definitions",
+            "acronyms": "standard-metadata.json:acronyms",
+        },
+        "metadata_covered_section_ids": covered,
+        "metadata_covered_count": len(covered),
+        "supporting_review_section_ids": supporting_review,
+        "supporting_review_count": len(supporting_review),
+        "unimplemented_supporting_section_ids": unimplemented,
+        "unimplemented_supporting_count": len(unimplemented),
+    })

api581/storage.py

@@ -0,0 +1,42 @@
+"""Local immutable result archive; create one repository per application instance."""
+import json
+from pathlib import Path
+try:
+    import sqlite3
+except ImportError as exc:  # pragma: no cover - exercised on stripped HPC images
+    # Some cluster Python builds ship the sqlite3 stdlib wrapper without the
+    # compiled `_sqlite3` extension.  A staged pysqlite3-binary wheel can
+    # provide the same DB-API surface without changing the public RunStore API.
+    if getattr(exc, "name", None) != "_sqlite3":
+        raise
+    try:
+        import pysqlite3 as sqlite3
+    except ImportError:
+        raise exc
+
+
+class RunStore:
+    def __init__(self, path: str):
+        self.path = path
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        with self.connect() as db:
+            db.execute("CREATE TABLE IF NOT EXISTS runs (run_id TEXT PRIMARY KEY, asset_id TEXT, calculated_at TEXT NOT NULL, payload TEXT NOT NULL)")
+            db.execute("CREATE INDEX IF NOT EXISTS runs_asset ON runs(asset_id, calculated_at)")
+
+    def connect(self):
+        return sqlite3.connect(self.path, timeout=30)
+
+    def save(self, result):
+        with self.connect() as db:
+            db.execute("INSERT INTO runs VALUES (?, ?, ?, ?)", (result["run_id"], result["context"].get("asset_id"),
+                       result["calculated_at"], json.dumps(result, allow_nan=False)))
+
+    def get(self, run_id):
+        with self.connect() as db:
+            row = db.execute("SELECT payload FROM runs WHERE run_id = ?", (run_id,)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def list(self, asset_id, limit):
+        with self.connect() as db:
+            rows = db.execute("SELECT payload FROM runs WHERE asset_id = ? ORDER BY calculated_at DESC LIMIT ?", (asset_id, limit)).fetchall()
+        return [json.loads(row[0]) for row in rows]

api581/sulfidic_corrosion.py

@@ -0,0 +1,197 @@
+"""2016 modified McConomy/naphthenic source tables and explicit edge policies."""
+from bisect import bisect_left
+from itertools import product
+from typing import Literal
+from pydantic import Field
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from ._sulfidic_tables import TABLES
+from .thinning import Posterior, WallLoss
+from .clad_thinning import PressureStrength, CodeStrength
+from .thinning_conditions import ThinningConditions, QualifiedUnclad, qualified_unclad
+
+Material=Literal['carbon_steel','cr1_0p2mo','cr1_0p5mo','cr1p25_0p5mo','cr2p25_1mo','cr3_1mo',
+    'cr5_0p5mo','cr7_1mo','cr9_1mo','cr12','austenitic_without_mo','ss_304','ss_304l','ss_321','ss_347','ss_316','ss_316l','ss_316h','ss_317']
+Group=Literal['carbon_steel','low_alloy','cr5','cr7','cr9','cr12','stainless_no_mo','stainless_low_mo','stainless_high_mo']
+Units=Literal['printed_si','printed_us_converted']
+_GROUPS=Group.__args__
+
+
+class SulfidicMaterial(Model):
+    material: Material
+    molybdenum_mass_fraction: Fraction | None=None
+
+
+@calculation('damage/sulfidic-material-selection','Sulfidic/naphthenic material and316 molybdenum source group',SulfidicMaterial,
+    ['Part2 Table2.B.3.1,Tables3.2-3.10M; PDF pp333-351'],limitations=[
+        'Named alloys only, no continuousCr interpolation.316/316L/316H withMo>=2.5wt% use high-Mo group, below use low; unknownMo assumes<2.5wt% per source and flags assumption.317source high-Mo group;Mo input only used for316family and rejected elsewhere. Austenitic-withoutMo includes304/304L/321/347. Actual composition/material suitability remains owner-qualified.'])
+def material_selection(x):
+    family=x.material in ('ss_316','ss_316l','ss_316h')
+    ensure(family or x.molybdenum_mass_fraction is None,'Mo concentration input applies only to316-family selection')
+    assumed=family and x.molybdenum_mass_fraction is None
+    if family:
+        group='stainless_low_mo' if assumed or x.molybdenum_mass_fraction<.025 else 'stainless_high_mo'
+    elif x.material=='ss_317': group='stainless_high_mo'
+    elif x.material.startswith('ss_') or x.material=='austenitic_without_mo': group='stainless_no_mo'
+    else: group={'carbon_steel':'carbon_steel','cr5_0p5mo':'cr5','cr7_1mo':'cr7','cr9_1mo':'cr9','cr12':'cr12'}.get(x.material,'low_alloy')
+    return {'table_group':group,'unknown_molybdenum_low_assumed':assumed}
+
+
+class SulfidicAxes(SulfidicMaterial):
+    unit_basis: Units
+
+
+@calculation('damage/sulfidic-table-axes','Sulfidic/naphthenic sulfur TAN and temperature-bin axes',SulfidicAxes,
+    ['Part2 Tables2.B.3.2-3.10M; PDF pp334-351'],limitations=[
+        'Material-specific sulfur andTAN grids, not common axes. CS sulfur0.6wt% versus5Cr0.75wt% and most others0.8wt% preserved. Lower temperature column<=232C/450F is interval, upper>399C/750F interval; neither invented finite node. Interior six temperature nodes exposed separately. Interpolation near first bin needs explicit threshold-anchor qualification. SI/US rates/temperatures retain rounding.'])
+def table_axes(x):
+    selected=material_selection(x)
+    data=TABLES[selected['table_group']+'_'+x.unit_basis]
+    temps=[t+273.15 for t in (232,260,288,315,343,371,399)] if x.unit_basis=='printed_si' else [(t-32)*5/9+273.15 for t in (450,500,550,600,650,700,750)]
+    return {**selected,'sulfur_mass_fraction_nodes':list(data['sulfur_mass_fractions']),'tan_nodes_mg_koh_g':list(data['tan_mg_koh_g']),
+        'lower_temperature_bin_upper_k':temps[0],'interior_temperature_nodes_k':temps[1:],'upper_temperature_bin_lower_exclusive_k':temps[-1],
+        'source_table_id':'2.B.3.'+str(_GROUPS.index(selected['table_group'])+2)+('M' if x.unit_basis=='printed_si' else '')}
+
+
+def _bracket(nodes,value):
+    tolerance=1e-14 if nodes[-1]<=.1 else 1e-10
+    value=next((n for n in nodes if abs(n-value)<=tolerance),value)
+    ensure(nodes[0]<=value<=nodes[-1],'Outside sulfidic sulfur/TAN/table range; no extrapolation')
+    i=bisect_left(nodes,value)
+    return (i,i,0.) if value==nodes[i] else (i-1,i,(value-nodes[i-1])/(nodes[i]-nodes[i-1]))
+
+
+class SulfidicTableRate(SulfidicAxes):
+    sulfur_mass_fraction: Fraction
+    tan_mg_koh_g: NonNegative
+    maximum_temperature_k: Positive
+    lookup_policy: Literal['exact_nodes_only','trilinear','maximum_bracketing_value']
+    temperature_edge_policy: Literal['reject_edge_bins_and_first_gap','qualified_source_bins_and_threshold_anchor']
+    temperature_edge_qualification_basis: str | None=None
+    low_tan_policy: Literal['reject_below_first_tan','qualified_first_tan_row']
+    low_tan_qualification_basis: str | None=None
+
+
+@calculation('damage/sulfidic-table-rate','Sulfidic/naphthenic sulfur TAN temperature base rate',SulfidicTableRate,
+    ['Part2 Annex2.B §3.3,Tables3.2-3.10M; PDF pp332-351'],limitations=[
+        '3840physical SI/US cells before velocity correction. Low/high temperature bins require qualified applicability and flag;232..260C/450..500F first-gap interpolation additionally uses qualified lower-bin threshold anchor, not invented source point. No interpolation from750F into open-ended>750bin; exact750 is interior last node, immediatelyabove uses upper bin. FirstTAN rows are literal nodes, not<=:below-first requires owner-qualified first-row extension/flag;above-last and sulfur outside table rejected. Concentration/TAN nonmonotonicities retained, including12Cr rate declines: no smoothing. Explicit trilinear/max-corner policy, not validated physical correlation. Naphthenic-influenced values only order-of-magnitude per source. No automatic gas-only acidity suppression or unknown-sulfur default.'])
+def table_rate(x):
+    axes=table_axes(x)
+    data=TABLES[axes['table_group']+'_'+x.unit_basis]
+    tq=x.temperature_edge_policy=='qualified_source_bins_and_threshold_anchor'
+    ensure((x.temperature_edge_qualification_basis is not None and bool(x.temperature_edge_qualification_basis.strip())) if tq else x.temperature_edge_qualification_basis is None,'Temperature policy and qualification basis must agree')
+    lq=x.low_tan_policy=='qualified_first_tan_row'
+    ensure((x.low_tan_qualification_basis is not None and bool(x.low_tan_qualification_basis.strip())) if lq else x.low_tan_qualification_basis is None,'Below-first TAN policy and basis must agree')
+    s0,s1,ws=_bracket(axes['sulfur_mass_fraction_nodes'],x.sulfur_mass_fraction)
+    below=x.tan_mg_koh_g<axes['tan_nodes_mg_koh_g'][0]
+    ensure(not below or lq,'TAN below first printed material-specific row')
+    a,b,wa=_bracket(axes['tan_nodes_mg_koh_g'],max(x.tan_mg_koh_g,axes['tan_nodes_mg_koh_g'][0]))
+    temp=x.maximum_temperature_k
+    nodes=[axes['lower_temperature_bin_upper_k']]+axes['interior_temperature_nodes_k']
+    bin_used=None; anchor=False
+    if temp<=nodes[0]:
+        ensure(tq,'Lower source temperature bin requires qualified high-temperature applicability')
+        i=j=0; wt=0.; bin_used='lower'
+    elif temp>nodes[-1]:
+        ensure(tq,'Open-ended upper temperature bin requires qualified applicability')
+        i=j=7; wt=0.; bin_used='upper'
+    else:
+        anchor=temp<nodes[1]
+        ensure(not anchor or tq,'First-bin-to-interior gap requires qualified threshold anchor')
+        i,j,wt=_bracket(nodes,temp)
+    ensure(x.lookup_policy!='exact_nodes_only' or (s0==s1 and a==b and i==j),'Exact sulfidic policy does not interpolate')
+    nt=len(axes['tan_nodes_mg_koh_g'])
+    def cell(s,t,c): return data['rates'][s*nt+t][c]
+    if x.lookup_policy=='maximum_bracketing_value':
+        native=max(cell(s,t,c) for s,t,c in product((s0,s1),(a,b),(i,j)))
+    else:
+        native=sum(fs*ft*fc*cell(s,t,c) for (s,fs),(t,ft),(c,fc) in product(((s0,1-ws),(s1,ws)),((a,1-wa),(b,wa)),((i,1-wt),(j,wt))))
+    return {'base_corrosion_rate_m_year':native*(.001 if x.unit_basis=='printed_si' else .0000254),'source_table_id':axes['source_table_id'],
+        'table_group':axes['table_group'],'unknown_molybdenum_low_assumed':axes['unknown_molybdenum_low_assumed'],
+        'source_temperature_bin_used':bin_used,'first_temperature_threshold_anchor_used':anchor,'below_first_tan_row_used':below}
+
+
+class SulfidicVelocity(Model):
+    velocity_m_s: NonNegative
+    boundary_interpretation: Literal['body_strictly_above_100ft_s','figure_at_or_above_100ft_s']
+    qualification_basis: str=Field(min_length=1)
+
+
+@calculation('damage/sulfidic-velocity-factor','Sulfidic/naphthenic high-velocity factor with100ft/s boundary policy',SulfidicVelocity,
+    ['Part2 Annex2.B §3.3,Figure3.1; PDF pp332,352'],limitations=[
+        'Factor5 above30.48m/s(100ft/s),1below. Body saysstrictly> while figure< test sends equality to5: explicit interpretation/basis determines exact boundary and conflict flag. No continuous velocity interpolation,hydraulic phase-velocity calculation or repeated5x in composition. Maximum nozzle/stream velocity applicability external.'])
+def velocity_factor(x):
+    ensure(bool(x.qualification_basis.strip()),'Velocity basis and source boundary interpretation qualification required')
+    boundary=x.velocity_m_s==30.48
+    high=x.velocity_m_s>30.48 or (boundary and x.boundary_interpretation=='figure_at_or_above_100ft_s')
+    return {'velocity_factor':5. if high else 1.,'velocity_boundary_conflict_encountered':boundary}
+
+
+class SulfidicThinningClassification(Model):
+    tan_mg_koh_g: NonNegative
+
+
+@calculation('damage/sulfidic-thinning-classification','Sulfidic/naphthenic TAN general/local source classification',SulfidicThinningClassification,
+    ['Part2 Table2.B.1.2; PDF p323'],limitations=[
+        'TAN<=0.5mgKOH/g general,>0.5local. Actual liquid-phaseTAN required,not whole-crude average or acid fraction. Classification does not establish mechanism presence or actual pit/inspection distribution; no velocity boundary from another table substituted.'])
+def thinning_classification(x):
+    return {'source_thinning_type':'general' if x.tan_mg_koh_g<=.5 else 'local'}
+
+
+class SulfidicService(Model):
+    table: SulfidicTableRate
+    velocity: SulfidicVelocity
+    liquid_phase_present: bool
+    hydrogen_free_sulfidation_and_tan_basis_qualified: bool
+    qualification_basis: str=Field(min_length=1)
+
+
+class SulfidicAssessment(Model):
+    sulfidic_service_present: bool
+    applicability_basis: str=Field(min_length=1)
+    service_model: SulfidicService | None=None
+
+
+@calculation('damage/sulfidic-corrosion-assessment','Qualified high-temperature sulfidic/naphthenic corrosion assessment',SulfidicAssessment,
+    ['Part2 Annex2.B §3,Tables3.1-3.10M,Figure3.1,Table1.2; PDF pp323,331-352'],origin='api581_composition_with_explicit_source_policies',limitations=[
+        'Same table rate*velocity factor once. Source hydrogen-free sulfidation and actual liquid-phaseTAN/material/process qualification required; highTAN>0.5 gas-only rejected,naphthenic attack needs liquid. Explicit working high-temperature scope>=204C or400F;below rejected,not immunity/zero. Above399C table upper bin retained with qualification,not automatic naphthenic decomposition discount. Source lowTAN first-row/Mo assumptions and edge flags retained. No-service0 specific,not totalDF0. No catalyticH2S/H2 substitution,phase equilibrium,McConomy curve digitization beyond printed tables or model certification.'])
+def assessment(x):
+    ensure(bool(x.applicability_basis.strip()),'Sulfidic mechanism and service applicability basis required')
+    if not x.sulfidic_service_present:
+        ensure(x.service_model is None,'No-sulfidic branch cannot carry unused source model')
+        return {'corrosion_rate_m_year':0.,'base_corrosion_rate_m_year':None,'source_table_id':None,'table_group':None,'unknown_molybdenum_low_assumed':False,
+            'source_temperature_bin_used':None,'first_temperature_threshold_anchor_used':False,'below_first_tan_row_used':False,
+            'velocity_factor':None,'velocity_boundary_conflict_encountered':False,'source_thinning_type':None,'calculation_branch':'no_sulfidic_service'}
+    ensure(x.service_model is not None,'Sulfidic service requires source model')
+    m=x.service_model
+    ensure(m.hydrogen_free_sulfidation_and_tan_basis_qualified and bool(m.qualification_basis.strip()),'Qualified hydrogen-free environment,material and actual phaseTAN required')
+    onset=204+273.15 if m.table.unit_basis=='printed_si' else (400-32)*5/9+273.15
+    ensure(m.table.maximum_temperature_k>=onset,'Below declared high-temperature sulfidic scope; no source-specific zero inferred')
+    ensure(m.liquid_phase_present or m.table.tan_mg_koh_g<=.5,'High-TAN naphthenic model needs liquid hydrocarbon phase')
+    base=table_rate(m.table); factor=velocity_factor(m.velocity)
+    return {**base,**factor,**thinning_classification(SulfidicThinningClassification(tan_mg_koh_g=m.table.tan_mg_koh_g)),
+        'corrosion_rate_m_year':base['base_corrosion_rate_m_year']*factor['velocity_factor'],'calculation_branch':'qualified_sulfidic_naphthenic_service'}
+
+
+class SulfidicThinning(Model):
+    corrosion: SulfidicAssessment
+    assessment_distribution: Literal['general','local']
+    distribution_qualification_basis: str=Field(min_length=1)
+    starting_thickness_m: Positive
+    elapsed_years: NonNegative
+    strength: PressureStrength | CodeStrength=Field(discriminator='method')
+    inspections: Posterior
+    conditions: ThinningConditions
+    qualification_basis: str=Field(min_length=1)
+
+
+@calculation('damage/sulfidic-thinning-assessment','Sulfidic/naphthenic rate through qualified unclad thinning DF',SulfidicThinning,
+    ['Part2 Annex2.B §3,Table1.2; §4.5.7,Table4.8'],origin='api581_composition_with_explicit_source_policies',limitations=[
+        'Same base*velocity-corrected rate drives wall loss once,dedicated high-temperature sulfidic/naphthenic monitoring row required. Actual distribution/inspection coverage owner-qualified independently of sourceTAN classification. Non-AST unclad only,no additional5x or unrelated H2S/H2 model. No-service0 retains generalDF floor/uncertainty;no all-mechanismDF,code/FFS acceptance or source-condition certification.'])
+def thinning_assessment(x):
+    ensure(bool(x.distribution_qualification_basis.strip()),'Actual distribution/inspection qualification required')
+    corrosion=assessment(x.corrosion)
+    ensure(x.conditions.monitoring.row.mechanism=='high_temperature_sulfidic_naphthenic','Sulfidic source requires dedicated monitoring row')
+    result=qualified_unclad(QualifiedUnclad(assessment_scope='non_ast_unclad',qualification_basis=x.qualification_basis,
+        wall=WallLoss(starting_thickness_m=x.starting_thickness_m,corrosion_rate_m_year=corrosion['corrosion_rate_m_year'],elapsed_years=x.elapsed_years),
+        strength=x.strength,inspections=x.inspections,conditions=x.conditions))
+    return {**corrosion,**result,'assessment_distribution':x.assessment_distribution}