API design
Mate Automation Interfaces
Public data contracts used by json-dump, MCO, mate, and explicit STEP highlights.
MateOutputConfig
Rationale
Generated project paths must be explicit and reviewable.
Purpose
Stores output directory, project filenames, overwrite policy, schematic sheet style, resolved rectangular board outline, board origin, and layer-stack template for a mate run.
Test Requirements
Mate tests must verify template defaults, D-size schematic setup, mate output outline modes, and generated project file creation.
Working Definition
Working when generated MCO paths and schematic sheet size are deterministic and writable under the selected output directory.
MateMarkerConfig
Rationale
Early generated boards need a simple visible marker for smoke validation.
Purpose
Configures optional marker text, position, height, and layer.
Test Requirements
Mate tests must read back generated PcbDoc marker text.
Working Definition
Working when enabling the marker produces one expected PCB text primitive.
MateKnownPartsConfig
Rationale
Legacy and compatibility workflows still need a reviewed boundary for generated fixture-part manifests.
Purpose
Stores the manifest path and cache directory for a known-parts cache. The Cricket public beta uses direct library roots instead, but the cache remains a tested compatibility path.
Test Requirements
Known-parts tests must verify node-test-array role metadata, manifest loading, role resolution, and compatibility with older mate configs.
Working Definition
Working when older configs can resolve fixture parts from a generated manifest without affecting the newer name-based library-root workflow.
MateLibrariesConfig
Rationale
Fixture part selection must be decoupled from source DUT files without requiring a generated manifest.
Purpose
Stores config-relative library roots and recursive scan policy for resolving mate_component.symbol_name and mate_component.footprint_name.
Test Requirements
Library tests must verify SchLib symbol names and PcbLib footprint names are discoverable, duplicate-free, and usable by MCO planning.
Working Definition
Working when projection code can resolve each selected target to copied library assets by name.
MatePlacementConfig
Rationale
Mating boards require repeatable coordinate transforms from DUT to output board.
Purpose
Stores source mount side, offset, mirror flags, and mirror origin in mils.
Test Requirements
Placement tests must verify mirrored and offset coordinates in generated MCO operations.
Working Definition
Working when source coordinates project to expected output component and label positions.
MatePcbLabelsConfig
Rationale
Signal labels need consistent style controls without baking one layout forever.
Purpose
Configures optional PCB net labels, side, offset, box sizing, centering, row and column spacing, auto-width padding, generated column headers, and text style arguments. Sides may be target-relative or board-edge columns.
Test Requirements
Label tests must verify generated MCO text arguments, board-edge column header and label positions, shared computed box widths, exclusion from the generated feature union, and PcbDoc read-back for styled labels.
Working Definition
Working when right, left, board-right, and board-left label placements can be generated from configuration while board-edge labels and headers stay manually movable after generation.
PcbNetLabelRequest
Rationale
Label layout needs a small request object so placement collection stays separate from board-edge column rendering.
Purpose
Captures the label configuration, selected target metadata, output designator, and derived board-edge row and column identity before MCO text operations are emitted.
Test Requirements
Label tests must verify board-edge requests are grouped into stable columns with generated headers, uniform computed label widths, and target-relative labels remain supported.
Working Definition
Working when mate planning can collect all candidate labels first, render them after the generated feature union, and keep the resulting text manually movable.
MatePcbDesignatorsConfig
Rationale
Generated mate boards need compact, readable designators without depending on each source footprint's text defaults.
Purpose
Configures post-placement PCB designator arrangement. The current placement is above the component, with configurable offset, width estimate, layer, font kind, font name, bold flag, and stroke width.
Test Requirements
Mate planning tests must verify the arrange operation is emitted with selected designators and style arguments. MCO tests must read back modified component-owned designator text.
Working Definition
Working when generated components keep component-owned designator text and the text is moved above the component with the requested style.
MateSelectionComponent
Rationale
Component projections need source identity, action, and placement facts after inspection.
Purpose
Represents one selected DUT component with designator, kind, footprint, layer, optional net, source position, pad geometry, and resolved mate-component action data.
Test Requirements
Planning tests must verify selected components become schematic and PCB MCO operations.
Working Definition
Working when reviewed selections can produce stable mate component placement.
MateSelectionPad
Rationale
Free pads and NPTH alignment holes can be mating targets without a source component.
Purpose
Represents one selected source pad with designator, kind, optional net, source placement data, and resolved mate-component action data.
Test Requirements
Planning tests must verify selected free pads create fixture parts and labels.
Working Definition
Working when free pads can be projected independently of component ownership.
MateSchematicNetRoute
Rationale
Generated schematic labels need to attach to real wires and avoid hiding nearby generated parts.
Purpose
Computes the generated schematic wire start, wire end, label position, pin orientation, and label orientation from the resolved mate symbol's signal pin hotspot. The current layout uses symbol-type groups, a widened grid, and default D-size sheet so wires and labels have clearance from neighboring symbols. Wire length is estimated from net-name length so the wire extends under the full label text.
Test Requirements
Planning and run tests must verify emitted schdoc.add-wire operations, grouped symbol positions, pin-directed point coordinates, label positions and orientations on the wire, and SchDoc read-back.
Working Definition
Working when every netted generated schematic symbol has a visible wire leaving in the symbol pin direction and the net label lands on that wire without covering a neighboring symbol group.
MateSelectionBoard
Rationale
Selections are board-scoped because a project can contain multiple PCB documents.
Purpose
Groups selected components, free pads, board outline vertices, and board cutout contours for one source board key.
Test Requirements
Inspection tests must verify board keys, component candidates, free-pad candidates, outline geometry, and cutout geometry.
Working Definition
Working when a config can isolate the intended source board before projections run.
MateBoardProjectionConfig
Rationale
Mate boards often need source board profile references and real mechanical openings.
Purpose
Configures source outline graphics and source internal cutout projection. Cutouts can emit Mechanical layer outline graphics, actual board-cutout regions, or both. cutouts.scope may keep all detected cutouts or filter to cutouts strictly interior to the source board outline.
Test Requirements
Mate tests must verify cutout graphic operations, pcbdoc.add-region operations with is_board_cutout, and interior-only cutout filtering.
Working Definition
Working when a generated mate plan can independently enable cutout references and manufacturable board cutouts while ignoring outline-adjacent routing cutouts when requested.
MateSelectionConfig
Rationale
Reviewed selections need a versionable root for generated plans.
Purpose
Aggregates selected board entries consumed by mate MCO planning.
Test Requirements
Template and planning tests must verify empty and populated selection configs.
Working Definition
Working when selected source objects can be loaded without re-running inspection.
MateConfig
Rationale
The command needs one reviewed config boundary before emitting MCO object code.
Purpose
Aggregates source, output, libraries, projection actions, designator, selection, board projection, and artifact configuration.
Test Requirements
Mate tests must load generated templates, examples, and hand-authored configs.
Working Definition
Working when a config can plan and run without hidden command-line state.
MateComponentCandidate
Rationale
Users need inspectable candidate data before committing to projections.
Purpose
Reports one source component candidate with classification, layer, position, footprint, net, and pad geometry.
Test Requirements
Inspection tests must verify component classification and source pad geometry extraction.
Working Definition
Working when likely test points and mounts are surfaced with enough data to seed a config.
MatePadCandidate
Rationale
Free pads require separate inspection output from component-owned pads.
Purpose
Reports one source pad candidate with kind, net, position, drill, plated state, optional source power-port metadata, and geometry.
Test Requirements
Inspection tests must verify NPTH classification, plated/unplated free-pad filtering, net preservation, and power-port metadata propagation.
Working Definition
Working when plated or unplated free pads can be selected for mating features and schematic power symbols can follow those selected nets.
MateBoardInspection
Rationale
Inspection output needs a durable board-level summary for config seeding.
Purpose
Groups board identity, board outline and cutouts, board origin, component candidates, and free-pad candidates.
Test Requirements
Inspection tests must validate outline, cutouts, origin, and candidate serialization.
Working Definition
Working when source board facts can be reviewed before plan generation.
AltiumLibraryEntry
Rationale
Library scans need a small stable record for each discoverable symbol or footprint name.
Purpose
Stores the public symbol or footprint name and the source SchLib/PcbLib path for CLI display, JSON output, and mate resolution.
Test Requirements
Library tests must verify entries are sorted, serialized, and resolve the expected Cricket mate parts from local library roots.
Working Definition
Working when a user can run libraries, see the name/path pairs, and reuse those names in a mate config.
AltiumLibraryScanResult
Rationale
Users need a direct way to confirm which symbols and footprints a config can resolve.
Purpose
Reports scanned roots, recursion policy, symbol entries, footprint entries, and parse warnings for the generic libraries command and the mate planner.
Test Requirements
Library tests must verify expected public sample symbols and footprints are listed and usable.
Working Definition
Working when a selected source object can resolve to the intended fixture part by symbol and footprint name.
MateKnownPartTemplate
Rationale
The legacy known-parts cache needs deterministic metadata for each fixture part role.
Purpose
Stores role, description, symbol/footprint names, library paths, target kinds, designator prefix, and optional signal pad mapping for one generated known part.
Test Requirements
Known-parts tests must verify the node-test-array templates produce manifest entries for pogo contacts, SMT standoffs, and alignment pins.
Working Definition
Working when compatibility cache generation emits enough metadata for older mate configs to resolve each supported target kind.
McoDocumentSession
Rationale
CAD operations need shared open/save behavior across one MCO run.
Purpose
Caches opened CAD documents, tracks dirty state, and flushes mutations at run exit.
Test Requirements
MCO tests must verify repeated mutations flush once and preserve in-memory state.
Working Definition
Working when operations do not expose low-level open, save, or close steps.
McoExecutionContext
Rationale
Operations need a consistent working directory, dry-run flag, and document session.
Purpose
Carries execution-scoped state for every MCO operation handler.
Test Requirements
CLI and operation tests must verify dry-run and work-directory behavior.
Working Definition
Working when handlers resolve paths and mutation policy consistently.
McoOperationSpec
Rationale
Raw JSON operations need a validated execution model.
Purpose
Represents one parsed operation id, operation name, args, message, and failure branch.
Test Requirements
Control-flow tests must verify duplicate ids, failure jumps, and loop rejection.
Working Definition
Working when malformed operations fail before CAD mutation.
McoOperationInfo
Rationale
Supported MCO commands need one maintained registry so users and agents can inspect the current operation surface.
Purpose
Stores operation name, functional group, summary, required args, and optional args for mco list and mco list --json.
Test Requirements
CLI tests must verify the catalog includes the public project, SchDoc, PcbDoc, file, and MCO operations.
Working Definition
Working when adding a supported operation requires adding metadata in the same registry used by the executor.
McoOperationResult
Rationale
Every operation needs a structured success or failure record.
Purpose
Reports operation id, op name, success, message, outputs, and optional error.
Test Requirements
MCO tests must verify success, failure, dry-run, and branch result payloads.
Working Definition
Working when command output can explain each operation outcome.
McoExecutionResult
Rationale
Callers need one aggregate MCO run result.
Purpose
Aggregates overall success, dry-run state, and ordered operation results.
Test Requirements
CLI run tests must parse and validate the emitted result JSON.
Working Definition
Working when generated workflows can detect failure without parsing logs.
McoProjectPrimitiveOperations
Rationale
Project creation must be inspectable as small appendable operations instead of one bundled skeleton command.
Purpose
Defines the project.create, schdoc.create, pcbdoc.create, project.add_document, project.add_parameter, and project.add_variant MCO operations used to author project bundles.
Test Requirements
MCO tests must verify generated projects can be mutated immediately after creation, requested schematic sheet styles and board origins are written, project documents preserve relative paths, and dry-run project mutations do not open unwritten files.
Working Definition
Working when project setup is predictable, ordered, dry-run safe, and ready for follow-on SchDoc/PcbDoc operations.
FileMutationPaths
Rationale
Mutation handlers need one path policy for input, output, and overwrite behavior.
Purpose
Stores resolved input file, output file, and whether the operation mutates in place.
Test Requirements
CAD operation tests must verify generated files are saved in the expected location.
Working Definition
Working when all mutation operations enforce the same target policy.
PcbDesignatorArrangementTarget
Rationale
Designator arrangement needs a small internal record that separates selected text from component lookup details.
Purpose
Stores the owning component index, normalized selection key, and display text for one PCB designator text object being arranged.
Test Requirements
MCO component-placement tests must verify that arranged designator text remains linked to the expected component index and display text.
Working Definition
Working when the arranger can target component-owned text by designator or component index without duplicating text primitives.
PcbDocArrangeDesignatorsOperation
Rationale
Generated workflows sometimes need to normalize placement-created designator text after footprint insertion.
Purpose
Moves component-owned PCB designator text above the owning component, estimates text width, and applies layer/font/style arguments while keeping the text linked to its component.
Test Requirements
MCO tests must place a component from a PcbLib, arrange its designator, save the PcbDoc, and read back position, size, font, bold flag, and component index.
Working Definition
Working when the operation mutates existing designator text without creating duplicate loose designator text.
JsonDumpOutput
Rationale
Batch JSON dumps need per-file source and output mapping.
Purpose
Records source path, output path, and document kind for one dumped document. Standalone json-dump supports by-kind folders such as pcbdoc/ and flat output directly under the selected output directory.
Test Requirements
JSON dump tests must verify manifest entries match written output files for by-kind and flat layouts.
Working Definition
Working when users can trace every JSON file back to its Altium source.
JsonDumpResult
Rationale
Batch dumps need one aggregate result for CLI and tests.
Purpose
Groups written outputs and optional manifest path for a json-dump run.
Test Requirements
JSON dump tests must verify project expansion and manifest creation.
Working Definition
Working when stdout and file-output modes can share result handling.
PcbLayerStepHighlight
Rationale
Generated mating-board workflows need explicit colored STEP overlay bodies tied to selected source pads.
Purpose
Stores highlight id, display name, color, source pad geometry, Z offset, and overlay thickness.
Test Requirements
MCO STEP export tests must verify highlight bodies are present in the geometer request.
Working Definition
Working when mate projections can color selected DUT pads independently of normal copper bodies.