Skip to content

Failure Recovery

Failure recovery starts with knowing which artifacts, interfaces, and tests expose the problem.

This page should help a maintainer stabilize the situation before they try to improve it. The first question is not always how to fix the bug; it is how to locate the right evidence quickly.

Treat the operations pages for bijux-canon-ingest as the package's explicit operating memory. They should make common tasks repeatable without relearning the workflow from logs or oral history.

Visual Summary

graph TD
    A[Failure Recovery] --> B[Detect failed run]
    B --> C[Classify failure mode]
    C --> D[Apply recovery path]
    D --> E[Re-run with traceability]
    E --> F[Restore stable operation]

Recovery Anchors

  • interface surfaces: CLI entrypoint in src/bijux_canon_ingest/interfaces/cli/entrypoint.py, HTTP boundaries under src/bijux_canon_ingest/interfaces, configuration modules under src/bijux_canon_ingest/config
  • artifacts to inspect: normalized document trees, chunk collections and retrieval-ready records, diagnostic output produced during ingest workflows
  • tests to run: tests/unit for module-level behavior across processing, retrieval, and interfaces, tests/e2e for package boundary coverage

Concrete Anchors

  • packages/bijux-canon-ingest/pyproject.toml for package metadata
  • packages/bijux-canon-ingest/README.md for local package framing
  • packages/bijux-canon-ingest/tests for executable operational backstops

Use This Page When

  • you are installing, running, diagnosing, or releasing the package
  • you need repeatable operational anchors rather than architectural framing
  • you are responding to package behavior in local work, CI, or incident pressure

Decision Rule

Use Failure Recovery to decide whether a maintainer can repeat the package workflow from checked-in assets instead of memory. If a step works only because someone already knows the trick, the workflow is not documented clearly enough yet.

What This Page Answers

  • how bijux-canon-ingest is installed, run, diagnosed, and released in practice
  • which checked-in files and tests anchor the operational story
  • where a maintainer should look first when the package behaves differently

Reviewer Lens

  • verify that setup, workflow, and release statements still match package metadata and current commands
  • check that operational guidance still points at real diagnostics and validation paths
  • confirm that maintainer advice still works under current local and CI expectations

Honesty Boundary

This page explains how bijux-canon-ingest is expected to be operated, but it does not replace package metadata, actual runtime behavior, or validation in a real environment. A workflow is only trustworthy if a maintainer can still repeat it from the checked-in assets named here.

Next Checks

  • move to interfaces when the operational path depends on a specific surface contract
  • move to quality when the question becomes whether the workflow is sufficiently proven
  • move back to architecture when operational complexity suggests a structural problem

Purpose

This page gives maintainers a durable frame for triaging package failures.

Stability

Keep it aligned with the package entrypoints and diagnostic outputs.