Interfaces

Open this section when the question is contractual: which ingest commands, schemas, records, artifacts, and imports are safe for another tool or package to rely on.

Contract Surface

Ingest exposes more than one kind of interface. Operators reach it through CLI and HTTP surfaces, package callers rely on imports and serialized records, and downstream packages consume artifacts that must remain stable enough to review. This section should name those promises before a reader has to inspect code.

flowchart LR
    caller["caller or operator"]
    cli["CLI surface"]
    api["API surface"]
    config["configuration"]
    data["prepared records"]
    artifacts["artifact contracts"]
    schema["tracked schema"]
    downstream["index handoff"]

    caller --> cli --> data
    caller --> api --> data
    caller --> config --> data
    data --> artifacts --> downstream
    data --> schema

The key contract idea is that ingest promises prepared material, not just commands. CLI, API, and configuration are only different entry doors into the same contract surface: deterministic records that another package can consume without guessing how they were shaped.

Read These First

• open Data Contracts first when the dispute is about record shape, chunk structure, or prepared payload layout
• open CLI Surface when the issue begins with an operator or scripted entrypoint
• open Compatibility Commitments when a surface change may break downstream assumptions

Contract Risk

The main contract risk here is letting downstream packages rely on visible ingest behavior that was never named as a real contract.

First Proof Check

• packages/bijux-canon-ingest/src/bijux_canon_ingest/interfaces for CLI, HTTP, serialization, and error bridges
• packages/bijux-canon-ingest/src/bijux_canon_ingest/config for caller-visible ingest, parsing, and cleaning settings
• apis/bijux-canon-ingest/v1/schema.yaml for tracked schema evidence
• packages/bijux-canon-ingest/tests and examples for proof that exposed ingest behavior is intentional

Pages In This Section

• CLI Surface
• API Surface
• Configuration Surface
• Data Contracts
• Artifact Contracts
• Entrypoints and Examples
• Operator Workflows
• Public Imports
• Compatibility Commitments

Leave This Section When

• leave for Foundation when the contract dispute is really a package-boundary dispute
• leave for Architecture when a surface question reveals structural drift underneath it
• leave for Operations or Quality when the boundary is clear and the question becomes execution or proof

Design Pressure

If callers can only learn what the package promises by reading implementation detail, the contract page is too weak. The stable record shapes and artifacts have to be visible here before they are convenient anywhere else.