Certificates & Class

Every certificate, survey, and class condition — tracked to its deadline.

Class compliance is the single largest operational risk a Technical Superintendent carries. A missed survey becomes a Condition of Class; a statutory certificate that lapses at sea is a detention waiting at the next port. This pipeline keeps the whole regulatory picture — class surveys, flag and statutory certificates, and the hazardous-materials inventory — visible, current, and audit-ready.

class surveysstatutory certsConditions of ClassCMSIHMPSC detention-riskflag overrides

Three regimes, one engine

Three bodies of regulation, one question: what’s expiring, and how exposed are we?

Class-issued — surveys, Conditions of Class, Continuous Machinery Survey, and class certificates. Read straight from the society portal (ABS, BV, DNV, LR, NK, CCS, KR, IRS, RINA).
Flag & statutory — everything class doesn’t issue: SOLAS, MARPOL, MLC, ISM, ISPS, BWM certificates, trade certs, registry, insurance. A typical vessel carries 30–50 of these beyond the class set.
Hazardous-materials inventory — the record of every hazardous substance on board, mandatory under the Hong Kong Convention and EU Ship Recycling Regulation (IHM), plus its Statement of Compliance.

All three run on the same machinery below.

The shared engine

Effective expiry is the later of the certificate or survey date and any flag-issued extension; days remaining drives the verdict:

D_effective = max(D_expiry, D_extension)
Δdays       = D_effective − D_today

Window	Bucket	Action
Already expired	CRITICAL	Vessel non-compliant — escalate immediately
0–30 days	HIGH	Renewal urgent
31–90 days	MEDIUM	Renewal in planning
91–180 days	LOW	Track
Beyond 180 days	OK	Routine

Flag override. Some flags issue full-term certificates that supersede the class-issued version — most commonly Panama for BWMC, IHM, or ISSC. These read as expired in the class portal but are administratively in order; without the override they throw a false-positive CRITICAL every review cycle.

Panama flag override (code)

if days_diff <= 0:
    name = cert.get("certificateName", "").lower()
    if any(t in name for t in ("ballast", "bwm", "hazardous", "ihm",
                                "security", "issc")) and "panama" in vessel_flag:
        verdict = "Full term certificate — flag-issued"
        severity = None     # Not overdue
    else:
        verdict = "Overdue"
        severity = "CRITICAL"

Class surveillance

The class society portal (ABS today, the same pattern for BV / DNV / LR / NK / CCS / KR / IRS / RINA) is scraped directly — structured data plus a screenshot of every page — so every number on the review traces to a timestamped snapshot. Class disputes are won on documentation, not arguments.

Surveys carry one state certificates don’t — a window period: a vessel is compliant if the survey completes inside the window, even after the formal due date.

Conditions of Class are operationally restrictive; Memoranda and Notes are advisory. An open Condition of Class near its deadline is the single highest-weight contributor to detention risk.
Continuous Machinery Survey (CMS) items are credited if completed within a 365-day window, otherwise classified by remaining days. Per-society precedence differs — RINA honours only the original due date; NK / LR / CCS / IRS / BV / ABS / KR / DNV consider an extension if present.

Survey status — the “In Window Period” state (code)

def calculate_survey_status(surveys):
    for survey in surveys:
        due_date          = parse_date(survey.get("dueDate"))
        window_start_date = parse_date(survey.get("windowStartDate"))
        window_end_date   = parse_date(survey.get("windowEndDate"))
        postponed_date    = parse_date(survey.get("extendedDate"))

        dates = [d for d in (due_date, postponed_date) if d]
        max_date = max(dates) if dates else window_end_date
        days_diff = (max_date - current_date).days if max_date else None

        if window_start_date and window_end_date \
           and window_start_date <= current_date <= window_end_date:
            status = "In Window Period"      # compliant inside the window
        elif days_diff is None:   status = "In Order"
        elif days_diff <= 0:      status = "Overdue"
        elif days_diff <= 90:     status = f"Due in {days_diff} days"
        else:                     status = "In Order"

Conditions of Class & findings classifier (code)

Findings are routed by the header they fall under — Conditions of Class (restrictive) vs Memoranda / Notes (advisory):

def determine_header(row):
    criticality = row["criticality"]
    if pd.isna(criticality):
        return "Notes"
    s = str(criticality).strip()
    if "CoC" in s:          return "CoC"
    sl = s.lower()
    if "exempti" in sl:     return "Exemption"
    if "memorand" in sl:    return "Memoranda"
    if "recommend" in sl:   return "Recommendation"
    return "Notes"

Every finding then gets the same effective-expiry classification using its own due and extended dates.

CMS crediting and the portal evidence trail

A CMS item is credited when last completed 1–365 days ago; otherwise it is classified by remaining days (Overdue / Due in N / In Order). Docking and next-periodical surveys use the same windowing but carry extra operational weight — they couple to drydock-slot booking, charter-party off-hire, and SIRE / vetting calendars.

Acquisition is append-only: a Playwright scraper verifies portal reachability, walks the pages (vessels list, overview, certificates, surveys, findings, assets), and saves the structured JSON plus a full-page screenshot per page into a timestamped folder. Re-running never overwrites earlier snapshots — historical class state is preserved.

case_files/vessels/{IMO}/class_surveys/
├── raw_data/abs_2026-04-30.json     # all scraped page responses
├── documents/certificates/*.pdf     # downloaded certificate copies
├── screenshots/01_vessels_list.png … 06_assets.png
└── activity_log.jsonl               # append-only run log

Statutory & trade certificates

The class portal handles class certificates; everything else lives here. Each flag and class society publishes differently — some via portal, some via PDF email — and the pipeline normalises every source into one record shape.

Category	Examples
Statutory	SOLAS, MARPOL, MLC, ISM, ISPS, BWM
Trade-specific	IOPP, ISPP, SOPEP, GAS Code, Polar Code
Registration	Registry certificate, Continuous Synopsis Record
Insurance	P&I, H&M
Operational	Minimum safe manning, cargo ship safety radio

Detention-risk scoring (type weights)

A composite weighted by certificate type and window urgency:

R_psc = Σᵢ ( w_type(cᵢ) · w_window(cᵢ) )

Certificate type	Weight
Statutory (SOLAS / MARPOL / MLC / IOPP)	5
Class (Hull / Machinery / Cargo Ship Safety)	4
Trade-specific (BWMC / IHM / ISSC)	3
Insurance (P&I / H&M)	2
Other (registry / wireless / etc.)	1

Long-lead-survey renewals get an additional multiplier — they can’t be rushed at the next port call. The composite maps to LOW / MEDIUM / HIGH / CRITICAL.

Renewal lead-time critical path

For each certificate due within 180 days the pipeline computes the renewal critical path:

Survey requirement (in-port vs underway)
Surveyor availability at the planned port
Document-preparation lead-time
Flag-administration processing time

A renewal needing 21 days lead-time when the vessel reaches the next port in 14 is a problem — the pipeline surfaces these timing gaps before the window closes.

Multi-vessel heat-map rollup

For fleet reviews the pipeline produces a heat-map table — one row per vessel, one column per certificate type, colour-coded by expiry window. A HIGH-bucket column spread across different months points to a process gap (renewal-coordinator capacity); the same bucket clustered in one month points to a calendar artefact (a whole class certificated together at delivery).

Hazardous-materials inventory (IHM)

The record of every hazardous material on board — where it is and how much — mandatory throughout the vessel’s life under the Hong Kong Convention and EU Ship Recycling Regulation. A vessel without a current IHM cannot be recycled at an EU-listed yard; a stale one is a dispute waiting at the next port-state inspection.

Statement of Compliance (SoC) — 5-year validity with an annual endorsement. Miss the endorsement window and the certificate is invalid even with years of validity left. Same window logic as the shared engine.
Part I currency — updated every time hazardous-material equipment is replaced or added, with a new Material Declaration (MD) and Supplier Declaration of Conformity (SDoC). Long quiet periods (no amendment in 18 months) get flagged for review.
Maintenance procedure — the Safety Management System document that tells the crew how to maintain the inventory. A mismatch between the written procedure and the actual update history is itself a finding.
Outstanding tasks — materials added without MD/SDoC, equipment replaced without update, items not yet validated by class — which combine into a compliance score:

IHM compliance % = tasks_completed_on_time / tasks_in_period × 100

Below 90% is a paper-trail gap that surfaces at the next class survey. The biggest preventable gap most fleets carry is missing supplier MD/SDoC for equipment replaced in service — cross-referenced against the PMS pipeline for completed major-component replacements without a matching IHM update.

Worked example — MV POSUN

One Panama-flagged snapshot (IMO 9388340, ABS classed), mid-April review, exercising all three regimes:

Regime	Finding
Class — survey	Annual hull survey overdue (postponed once already)
Class — CoC	Steering-gear test Condition of Class due in 18 days; a second CoC in 45
Class — CMS	Turbocharger inspection overdue
Statutory	IAPP (MARPOL VI) renewal in 21 days — HIGH; Cargo Ship Safety Equipment in 35
Shared override	BWMC expired 7 days ago → flag full-term, classified green (no action)
IHM	SoC valid to 2028; Part I last amended 7 months ago; turbocharger MD/SDoC not filed; compliance 87%

Detention-risk: HIGH — driven by the overdue annual hull survey and the 18-day steering-gear Condition of Class. The pipeline tags escalation_required, raises the case to CRITICAL, and routes it to the Technical Superintendent with the snapshot and recommended actions:

Schedule the annual hull survey at the next port — coordinate the surveyor window (≈ USD 4–6k).
Steering-gear function test before the CoC deadline.
IAPP renewal — surveyor coordination; vessel due Singapore in 11 days, lead-time tight but feasible.
Chase the turbocharger MD/SDoC from the supplier — until it is filed the IHM is incomplete and any class survey will surface the gap.
Log the BWMC override — no action needed.

Escalation triggers

Full escalation matrix (class · statutory · IHM)

Trigger	Severity
Any survey overdue	CRITICAL
Condition of Class within 30 days unresolved	CRITICAL
Class status downgraded	CRITICAL
Any statutory certificate expired (no override applies)	CRITICAL
Mandatory certificate missing	CRITICAL
IHM SoC expired or annual endorsement missed	CRITICAL
Detention-risk score HIGH or CRITICAL	CRITICAL
Open critical finding older than 60 days	HIGH
Recurring deficiency theme (3+ findings on same system)	HIGH
CMS item overdue	HIGH
Renewal lead-time insufficient for next port call	HIGH
Multiple HIGH-window renewals with no plan	HIGH
RO authorisation lapsed	HIGH
IHM outstanding task overdue beyond 60 days	HIGH
IHM compliance below 80%	HIGH
IHM maintenance procedure not revised in over 24 months	MEDIUM

Why script-driven

Surveys, certificates, and IHM are quantitative — dates and rules. Threshold logic, per-society precedence, type weighting, and compliance scoring all live in deterministic Python; the language model interprets the result and writes the review, it never recomputes the verdicts. That keeps reviews consistent across vessels and audits, traceable (every figure traces to a dated snapshot), and cheap to run. Manual reviews are where errors compound — one wrong date in a spreadsheet cell is inherited by the next four reviews.