io.github.praxec/fmeca

READ-ONLY. Read an analysis under a declarative risk policy and SUGGEST actions; it never changes the analysis or appends to the log. Pass exactly one of session_id or analysis ({matrix_strategy?, failure_modes[]} as for analyze). Optional: policy (a preset name or a file name in .fmeca/policies/, no paths; default compat-0.1), as_of (YYYY-MM-DD; default today, UTC; echoed back), bands[] (keep failure modes in these effective bands), tags[] (keep actions with any of these tags), required_only (keep only required actions), group_by (failure_mode|band|tag|action). Roll-ups and signoff always cover the whole analysis. Returns {policy{name,hash,class,matrix_derived_from,source}, as_of, failure_modes[]{id, inherent_band, residual_band, effective_band, confidence, fallback?, status, rationale_needed, actions[]}, excluded[], rollups, signoff{pass,reasons[]}, groups?}. Errors: POLICY_NOT_FOUND, INVALID_POLICY, POLICY_STRATEGY_MISMATCH; a malformed as_of reports INVALID_POLICY: date: ....

Stateless one-shot FMECA: hand it an ENTIRE analysis in one call, get back the ENTIRE computed report. NO session, NO persistence, NO event log — (input) → (computed report), deterministic + idempotent. Uses the SAME kernel compute as the session path (criticality matrix, residual, standing, response_class, readiness) so it cannot diverge. Args: optional matrix_strategy (qualitative3x3 (default) | nasa8004_5x5) + failure_modes[] — each {id, component{id}, description, cause?, effect?, domain, scope?, severity_observations[], probability_observations[], mitigations[]{id, kind, description, residual_severity_observations[], residual_probability_observations[]}}. ALL observation arrays (incl. the residual ones) are ids from scoring.catalog for the SELECTED strategy (NOT scores). Returns {matrix_strategy, failure_modes[]{id, criticality, residual_criticality, standing, response_class, issues[]}, risk_ranking[] (fm ids, highest risk first), issues[], ready, blockers[]}. An unknown observation id → INVALID_OBSERVATION.

Append one event. Tagged by `variant`: add_failure_mode{session_id, failure_mode} | add_mitigation{session_id, mitigation} | rescore{session_id, rescore} | set_mitigation_status{session_id, mitigation_id, status (planned|implemented|verified|abandoned), evidence?[]{kind, reference, basis?}, note?} (verified needs evidence whose kind is not note) | set_failure_mode_disposition{session_id, failure_mode_id, disposition (open|accepted|excluded), rationale, approver?, evidence?[]} (accepted needs an approver; excluded needs evidence whose kind is not note). The server stamps `at` on status and disposition changes. Never delete a failure mode: exclude it. A failure_mode / rescore supplies severity_observations + probability_observations, and a mitigation supplies residual_severity_observations + residual_probability_observations (all ids from scoring.catalog) — NOT a score; the engine derives every level. Returns the recomputed FmecaState with freshly-computed criticality + signals.

READ-ONLY. List the risk policies actions.suggest accepts: {presets[], project[]}, each {name, hash, class, description, source}. Project policies are the files in .fmeca/policies/; one that fails to load is listed with an error instead of failing the call.

Compute the ReadinessReport: ready bool + residual-criticality buckets + blockers. Ready iff every failure mode is scored, no residual High/Medium remains, and no weak_mitigation_order issue stands.

Emit the FMECA report: a row per failure mode (component, domain, cause, effect, criticality, residual, standing, response_class, mitigations), residual buckets, an explicit accepted-risks section, and the verbatim blockers.

The highest-criticality UNMITIGATED failure mode to address next. Returns {risk: null} when nothing unmitigated is High/Medium.

The fixed evidence→score catalog for a strategy: criteria{id, axis (severity|probability), level_ordinal, level (label), description} + the selected matrix_strategy. Optional matrix_strategy arg (default qualitative3x3). Supply these ids as severity_observations / probability_observations on append — the engine maps observations to a strategy-relative level (MAX-combine) and the matrix collapses it to criticality (low|medium|high). The model never supplies a score. A session's ACTIVE catalog is also embedded in session.open / state.get.

List the analyses in the state dir (the project's .fmeca/ when there is one). Optional exact-match filters: level, aspect, parent. Returns {state_dir, sessions[]} sorted by session_id; each row is {session_id, title, level, aspect, scope_paths, parent, failure_modes (count, excluded ones left out), by_standing{unmitigated, under_mitigated, acceptable}, excluded (count), ready, ready_verified, resolution{planned, implemented, verified, abandoned}, critical_items (count), accepted_risks (count)}. A log that fails to replay is listed as {session_id, error} instead of failing the call (such rows are kept whatever the filters).

Start or resume a session by session_id. Optional matrix_strategy SELECTS the criticality matrix (closed set: qualitative3x3 (default) | nasa8004_5x5); a session's strategy is fixed once opened, and you SELECT it — you cannot edit its cells. Optional analysis metadata, also fixed once opened: title, level (concept|conops|technical_plan|project_plan|implementation|verification), aspect, scope_paths[] and parent (an existing session id). Convention: session_id = <aspect>-<level>. Returns the current FmecaState including meta, matrix_strategy, matrix_scale, the active scoring_catalog, the component registry, computed criticality, signals, and readiness.

Read-only FmecaState projection: failure modes with computed criticality/residual/standing + mitigations + issues + signals + registry + readiness.

ADVISORY second opinion from Jev (a calibrated judgment model on OpenRouter; needs OPENROUTER_API_KEY). Pass exactly one of session_id or analysis (the analyze args shape). Asks up to max_questions (default 40, max 200) in four checks: observations (do the claimed scoring.catalog observations apply; does the next level up?), mitigations (how fully each addresses the cause; is its declared kind right?), coverage (failure classes no failure mode covers) and readiness (sound enough to sign off?). Returns {status: ok, model, usage{cost}, readiness_gate, findings[]{check, target, question_hash, probability, threshold, verdict (flag|ok; readiness concern|ok)}, skipped[] (unsent question hashes), questions_sent} or {status: vet_unavailable, reason (no_key|timeout|http_4xx|http_5xx|network|bad_response|bad_config), detail, readiness_gate}. NEVER writes and NEVER changes a score: the readiness_gate is the deterministic one; findings are probabilities to weigh, not verdicts. Excluded failure modes are skipped.