# Athena Domain - Features

> Planned Maker Intelligence and Workshop Operations Platform (TODO Phases 67
> and 136)

Athena is the planned Oshun domain for maker operations and workshops: CAD/CAM,
material science, wood/metal/glass/luthiery craft, smart furniture, firmware and
electronics, acoustics, CNC and additive manufacturing, workshop robotics,
simulation, production, supply chain, quality, ERP, marketplace, sustainability,
aftercare, compliance, and academy. Phase 136 additionally makes Athena the
owner of a sovereign engineering design kernel — CAD, EDA, CAM, and GIS — that
replaces proprietary engineering applications.

There are currently no `apps/athena/*` or `libs/athena/*` packages. This
document specifies the planned scope: behavior, parameters, states, and
acceptance criteria for each package area, so implementation begins against a
defined contract rather than a term list.

## Domain Foundation

Three core domain objects, defined in `specifications.md`, anchor every package.
Understanding these objects is the starting point for any Athena implementation:
they appear in the type signatures, state machines, and event contracts of
nearly every package in both Phase 67 and Phase 136.

**`DesignArtifact`** — any design output, with `id`, an `artifactType` of
`cad_model | drawing | toolpath | firmware | pattern | assembly_instruction`, a
`version` string, a `materialRequirements` list of `MaterialLotId`, and a
`status` of `draft → validated → released → archived`. Only `released` artifacts
may drive a `FabricationJob` or back a marketplace listing; `draft` and
`validated` are work-in-progress; `archived` is superseded but retained.

**`FabricationJob`** — a unit of physical making, with `id`, `workshopId`, the
`designId` it executes, a `process` of
`cnc | additive | woodcraft | metalcraft | glasscraft | electronics | assembly | finishing`,
and a `status` of `planned → queued → running → inspection → complete`, with
`failed` reachable from `running` or `inspection`. A job advances to `running`
only when its design is `released` and the required tools are not `locked_out`.

**`Tool`** — a physical or machine tool, with `id`, a `toolType` of
`hand_tool | cnc_machine | printer | robot | kiln | lathe | loom | test_fixture`,
a `certificationRequired` flag, and a `maintenanceStatus` of
`ready | due | locked_out | retired`. A `ready` tool may be used; `due` permits
use with a warning; `locked_out` and `retired` block job execution entirely.

### Hard Requirements

These four requirements reflect the physical consequences of the domain: a
machine tool that runs on unverified G-code can destroy a workpiece; a
marketplace that ships furniture without traceable quality records has no
accountability; a sustainability claim without evidence is greenwashing. Each
requirement is enforced at the type and state-machine level, not just as a
policy guideline.

Four platform requirements constrain every package and are non-negotiable:

1. **Tool certification and safety state.** Machine-control workflows enforce
   tool certification and `maintenanceStatus`. A `FabricationJob` cannot run on
   a `locked_out` or `retired` tool, and cannot be assigned to an artisan
   lacking the required certification for a `certificationRequired` tool.
2. **Versioned, reproducible releases.** Released `DesignArtifact`s — including
   `cad_model`, `drawing`, `toolpath`, and `firmware` types — are versioned and
   reproducible. Re-running a `released` toolpath against the same stock and
   machine profile produces the same G-code.
3. **Provenance with evidence.** Material provenance and sustainability claims
   retain their supporting evidence. A claim ("FSC-certified oak", "recycled
   aluminium") is backed by a `MaterialLot` record with attached documentation,
   not asserted free-standing.
4. **Marketplace traceability.** Every marketplace listing links back to the
   `released` `DesignArtifact` it sells and the quality records of the
   `FabricationJob`s that produced it.

---

# Phase 67 — Maker and Workshop Operations

Phase 67 covers the workshop operating system: the core entities, craft
verticals, smart-product engineering, production floor, and the business and
learning surfaces around them.

## `@athena/core`

Foundation package: the primitives every other package depends on.

- **Entity models** — workspace, project, `DesignArtifact`, `MaterialLot`,
  `Tool`, machine, artisan, shop, bill of material, work instruction,
  `FabricationJob`, order, customer, supplier, quality record, and safety
  record, each with a stable ID type (`WorkshopId`, `DesignId`, `MaterialLotId`,
  `FabricationJobId`, `ToolId`).
- **State machines** — owns the `DesignArtifact`
  (`draft → validated → released → archived`) and `FabricationJob`
  (`planned → queued → running → inspection → complete | failed`) transition
  graphs, rejecting illegal transitions and stamping each with actor and
  timestamp.
- **Event contracts** — typed events (`design.released`, `job.status_changed`,
  `tool.locked_out`, `material.received`, `quality.recorded`) consumed by other
  packages and downstream domains.
- **Bills of material and work instructions** — a BOM links a design to its
  `MaterialLot` requirements and component quantities; work instructions
  sequence the steps a `FabricationJob` executes.

## `@athena/cad`

Parametric CAD modeling for the maker workflow (the sovereign kernel is Phase
136, below).

- **Sketches and constraints** — 2D sketches with geometric and dimensional
  constraints; the sketch is solved before features build on it.
- **Solids and assemblies** — feature-based solids and multi-part assemblies
  with joints; configuration tables produce design variants from one model.
- **Tolerances and material assignment** — dimensions carry tolerances; parts
  carry a `MaterialLot` requirement so downstream costing and provenance work.
- **Revision history and drawings** — every model edit is a revision; production
  drawings are generated as `drawing`-type `DesignArtifact`s.
- **Design validation** — checks geometry for buildability before a model can be
  promoted from `draft` to `validated`.

## `@athena/cam`

CAM for the maker workflow: planning the cuts that realize a design.

- **Tool libraries and feeds/speeds** — tools are defined with geometry and
  recommended feeds and speeds per material.
- **Toolpaths and stock setup** — toolpaths are generated against a defined
  stock model and origin; nesting packs multiple parts onto one stock sheet.
- **G-code generation** — toolpaths post-process to G-code for a machine
  profile; the resulting `toolpath` artifact is versioned and reproducible (hard
  requirement 2).
- **Subtractive QA** — generated paths are checked for collisions and remaining
  stock before release (full validation is specified in the Phase 136 CAM
  packages — `@athena/cam-milling`, `cam-additive`, `cam-other` — below).

## `@athena/materials`

Material science: properties, availability, and substitution.

- **Material catalog** — wood, metals, glass, textiles, composites, finishes,
  adhesives, fasteners, and acoustical materials, each with mechanical
  properties (strength, hardness, density), workability, and finish behavior.
- **Sustainability attributes** — each material carries sourcing and
  sustainability attributes backed by evidence (hard requirement 3).
- **Availability and substitution** — material availability feeds procurement;
  substitution logic proposes alternatives when a `MaterialLot` is unavailable,
  ranked by property match, and never substitutes across a structural-property
  gap that the design depends on.

## Craft Verticals

Ten packages each specialize the core for a single material discipline:
`@athena/woodcraft`, `@athena/metalcraft`, `@athena/glasscraft`,
`@athena/luthiery`, `@athena/living`, `@athena/upholstery`, `@athena/finishing`,
`@athena/restoration`, `@athena/packaging`, and `@athena/aftercare`. Every
vertical defines, for its discipline:

- **Operations** — the craft-specific processes (e.g. woodworking joinery, metal
  forming and welding, glass blowing and annealing, instrument carving and
  fretwork, upholstery foam and fabric work, finishing coats, restoration
  conservation passes).
- **Tools and defects** — the `Tool` types used and the discipline's
  characteristic defects (tear-out, warp, weld porosity, glass stress fracture,
  fret buzz, finish runs) that quality gates check for.
- **Tolerances and quality gates** — discipline-appropriate tolerances and the
  `inspection`-stage gate a `FabricationJob` must pass before `complete`.
- **Documentation** — work instructions and provenance records for the craft.

`@athena/luthiery` additionally produces acoustic specifications and integrates
with `@athena/acoustics`; `@athena/living` covers IoT-enabled furniture and
integrates with the smart-product packages; `@athena/restoration` adds a
condition-assessment step that grades an incoming piece before a restoration job
is planned.

## Smart Products — `@athena/iot`, `firmware`, `electronics`, `acoustics`

The smart-product engineering stack for connected furniture and instruments.

- **`@athena/electronics`** — sensors, actuators, power, and connectivity
  hardware design; PCB-level work bridges to the Phase 136 EDA kernel.
- **`@athena/firmware`** — embedded software for smart products, produced as
  `firmware`-type `DesignArtifact`s that are versioned and reproducible (hard
  requirement 2).
- **`@athena/iot`** — device connectivity, diagnostics, telemetry, and lifecycle
  service for deployed smart products.
- **`@athena/acoustics`** — acoustic engineering: material acoustic properties,
  resonance and damping analysis, and acoustic specifications for instruments
  and acoustically-tuned furniture.

## Production Floor — `@athena/cnc`, `additive`, `robotics`, `simulation`, `workshop`, `production`, `supply`

The packages that turn released designs into finished pieces.

- **`@athena/cnc`** — subtractive machining execution: machine profiles, work
  offsets, fixturing, and the running of `cnc`-process `FabricationJob`s.
- **`@athena/additive`** — additive manufacturing: slicing, support generation,
  infill, build orientation, print profiles for resin/FDM/SLS/metal, and
  material-shrinkage compensation; runs `additive`-process jobs.
- **`@athena/robotics`** — workshop robots and machine tending: motion planning,
  safety zones, and robot-tended job execution; a robot is a `Tool` of type
  `robot` and is subject to the certification and lockout requirement.
- **`@athena/simulation`** — process simulation, virtual commissioning,
  ergonomic analysis, and digital-twin modeling of the shop, run before physical
  jobs to catch collisions and bottlenecks.
- **`@athena/workshop`** — shop layout, work centers, and machine reservations;
  reservations prevent two jobs claiming one machine.
- **`@athena/production`** — the MES: travelers, production batches, capacity
  planning, and scheduling; drives `FabricationJob`s through their state graph.
- **`@athena/supply`** — procurement, `MaterialLot` receiving, inventory, vendor
  performance scoring, and shipping readiness.

### Tool Certification and Safety Lockout State Machine

This state machine is the mechanical enforcement of Hard Requirement 1. It is
owned jointly by `@athena/workshop` (which manages the physical tool inventory)
and `@athena/quality` (which records inspection outcomes). The four states model
the real-world lifecycle of a shop-floor machine: from normal operation, through
scheduled maintenance, to emergency lockout, and finally permanent retirement.

Owned across `@athena/workshop` and `@athena/quality`, this enforces hard
requirement 1. A `Tool`'s `maintenanceStatus` follows:

- **`ready`** — the tool passed its last maintenance check; jobs may run.
- **`due`** — a scheduled maintenance interval has elapsed; jobs may still run
  but the operator is warned and the next check is escalated.
- **`locked_out`** — the tool failed inspection, reported an incident, or was
  manually locked by a supervisor; **no `FabricationJob` may run on it**, and
  the lockout records actor and reason. Clearing the lockout requires an
  explicit passed-maintenance event.
- **`retired`** — the tool is permanently withdrawn; it cannot be used and
  cannot return to service.

Independently, a `certificationRequired` tool checks the assigned artisan's
certification record at job assignment; an uncertified assignment is rejected,
not warned.

## Business, Marketplace, Academy — `@athena/erp`, `quality`, `studio`, `marketplace`, `compliance`, `sustainability`, `academy`

- **`@athena/erp`** — quotes, orders, invoices, and margin tracking; margin is
  computed from BOM material cost and labor.
- **`@athena/quality`** — quality records, the `inspection`-stage gate, defect
  tracking per craft vertical, and anomaly detection across jobs.
- **`@athena/studio`** — collaborative design space: shared projects, comments,
  markups, and review.
- **`@athena/marketplace`** — catalog, listings, and custom commissions; every
  listing links to a `released` `DesignArtifact` and the producing jobs' quality
  records (hard requirement 4).
- **`@athena/compliance`** — regulatory compliance records and audit trails for
  products and processes.
- **`@athena/sustainability`** — material and process sustainability accounting,
  with claims backed by evidence (hard requirement 3).
- **`@athena/academy`** — maker training content, cohorts, and certifications;
  certification completion feeds the tool-certification check.

## Platform — `@athena/apps`, `@athena/ai`, `@athena/biome`, `@athena/integration`

- **`@athena/apps`** — the application suite: a web app, a workshop floor
  console, a marketplace storefront, a design studio, and a mobile app.
- **`@athena/ai`** — design copilot, manufacturability checking, materials
  recommendation, restoration assessment, and quality anomaly detection;
  supports other packages rather than being a standalone surface.
- **`@athena/biome`** — factory-biome environmental modeling: temperature,
  humidity, dust, and their effect on materials and finishing.
- **`@athena/integration`** — the cross-domain hub that connects Athena to
  neighboring domains without re-modeling their facts. It provides adapters for:
  Seshat (design/craft intelligence), Brigid (industrial-scale factory
  automation), Cybele (the built environment where Athena's furniture is
  installed), Euterpe (digital music creation, which uses Athena-built
  instruments), and Maat (business rollups). Keeping integration logic in one
  place prevents other Athena packages from growing direct dependencies on
  external domain schemas.

## Relationship to Seshat

Seshat currently covers design, craft, fabrication, smart manufacturing,
sustainability, and maker education. Athena is a planned expansion into a deeper
maker/workshop operating system that overlaps Seshat's scope substantially.
Because both domains model similar things — materials, tools, fabrication
processes — the boundary between them cannot be left implicit. Before any Athena
package is implemented, ownership must be explicitly resolved: either split the
bounded contexts with a documented boundary, or fold Athena's workstreams into
Seshat with a documented migration. Athena must not silently duplicate Seshat.

---

# Phase 136 — Sovereign CAD / EDA / CAM / GIS Kernel

Phase 136 makes Athena the owner of a sovereign engineering design kernel that
replaces proprietary CAD, EDA, CAM, and GIS applications — tools like
SolidWorks, KiCad, Fusion 360, and QGIS — with first-party implementations owned
and maintained within the Oshun platform.

The division of labor between Athena and the Neith domain is fixed and important
to understand. **Neith** provides the low-level runtime, renderer, GPU compute,
file I/O, UI, collaboration, and platform substrate — the "operating system" on
which design tools run. **Athena** owns the engineering semantics layered on
top: geometry representations, constraint solving, manufacturing output formats,
design validation rules, and the domain feature set specific to CAD, EDA, CAM,
and GIS. This split ensures that rendering or platform changes stay in Neith,
while changes to how geometry is modeled or toolpaths are generated stay in
Athena.

## Geometric Modeling Kernel — `@athena/kernel`

The boundary-representation (B-rep) geometry engine.

- **Topology** — the B-rep model: bodies, shells, faces, loops, edges, vertices,
  and wires with orientation and adjacency. Provides Euler operators, manifold
  validation, topology healing, persistent naming (so feature references survive
  edits), and robust Boolean topology.
- **Curves** — lines, arcs, circles, ellipses, conics, splines, and NURBS, with
  trimming, offsets, intersections, projection, curve fitting, continuity
  analysis, and both exact and approximate evaluation.
- **Surfaces** — analytic surfaces (plane, cylinder, cone, sphere, torus), ruled
  surfaces, lofts, sweeps, and NURBS patches, with trims, offsets, blends,
  fillets, intersections, surface fitting, curvature analysis, and repair.
- **Solids and features** — extrude, revolve, sweep, loft, thicken, shell,
  draft, rib, hole, pattern, mirror, and Boolean union/subtract/intersect.
  Features replay from a history tree; rollback re-evaluates from a point;
  dependency tracking propagates downstream edits; non-manifold guards reject
  invalid results.
- **Analysis and validation** — mass properties, center of gravity, moments,
  interference and clearance checks, draft and wall-thickness analysis,
  curvature and zebra/reflective analysis, water-tightness, and tolerance
  checks. A model passing geometry QA is eligible to become a `validated`
  `DesignArtifact`.

## Constraint Solving — `@athena/constraint`

The 2D sketch and 3D assembly constraint solver.

- **2D sketch solver** — supports coincident, parallel, perpendicular, tangent,
  concentric, equal, horizontal/vertical, symmetry, and midpoint constraints
  plus driving dimensions. The solver classifies a sketch as
  **well-constrained** (one solution, fully determined), **under-constrained**
  (degrees of freedom remain — the sketch can still be dragged), or
  **over-constrained** (redundant or conflicting constraints — the solver
  reports the conflicting set rather than silently dropping one). Driven
  dimensions are reported, not solved for. The solver returns a human-readable
  explanation of why a sketch failed.
- **3D assembly mates** — concentric, coincident, distance, angle, gear, cam,
  slot, hinge, slider, and path mates; rigid and flexible subassemblies;
  exploded views; motion limits; collision-aware dragging; and mate-conflict
  resolution.
- **Solver internals** — sparse equation systems solved by Newton /
  Levenberg-Marquardt iteration, with graph decomposition to solve independent
  constraint clusters separately, constraint ranking, tolerance propagation, and
  incremental re-solve on edit. The solve is deterministic so it can be replayed
  exactly, and regression tests pin known sketches to known solutions.

## CAD Studio — `@athena/cad-studio`

The full mechanical CAD application surface on the kernel.

- **Sketcher and parametric modeling** — sketch planes, construction geometry,
  dimensions and relations, a feature tree, direct (history-free) modeling,
  history editing, configurations, design tables, equations, and named
  parameters and variants.
- **Assemblies and drawings** — part and assembly references, BOMs, exploded
  views, section and detail views, drawing sheets, GD&T, dimensions and
  tolerances, title blocks, revision tables, templates, and standards-aware
  annotation.
- **Sheet metal, weldments, surfacing** — flanges, bends, hems, unfold/refold,
  and flat patterns for sheet metal; weldment profiles and cut lists; Class-A
  surfacing with continuity tools, patching, trims, and surface-to-solid
  workflows.
- **Interchange** — STEP, IGES, and Parasolid/SAT-compatible import; STL, OBJ,
  3MF, glTF, and USD; DXF/DWG-compatible flows where legally supportable. Every
  exchange preserves metadata, units, and tolerances and is round-trip
  validated.

## EDA — `@athena/eda`

Electronic design automation: schematic, board, and verification.

- **Schematic capture** — symbols, nets, buses, hierarchical sheets, electrical
  rule checking (ERC), annotations, variants, simulation hooks, reusable blocks,
  and library management.
- **PCB layout** — footprints, layer stackups, design rules, interactive and
  assisted routing, differential pairs, length matching, copper planes, vias,
  zones, controlled impedance, thermal reliefs, design rule checking (DRC), 3D
  board preview, and manufacturing outputs.
- **Simulation and verification** — SPICE-style circuit simulation, signal- and
  power-integrity hooks, thermal checks, BOM validation, component lifecycle and
  substitution, supply-chain availability, and design-for-test.
- **Outputs** — Gerber / ODB++-class manufacturing packages, pick-and-place
  files, drill files, assembly drawings, panelization, fabrication notes, test
  points, and release packages.

## CAM, CNC, and Additive — `@athena/cam-milling`, `cam-additive`, `cam-other`

Toolpath generation and the validation that gates it. This is the spec's
nominated focus: strategies plus a hard validation gate.

- **Toolpath strategies** — 2.5D, 3-axis, and 4/5-axis paths; adaptive clearing,
  pocketing, contouring, drilling, tapping, engraving, surfacing, and rest
  machining; finishing and smoothing passes; lead-in/lead-out and tabs; and
  collision-aware planning. Each strategy is parameterized by tool, stepover,
  stepdown, and feeds/speeds.
- **Machines and posts** — machine kinematics, work offsets, tool libraries,
  feeds and speeds, stock models, fixtures and clamps, post-processors,
  controller dialects, G-code simulation, and shop-floor package export.
- **Additive manufacturing** — slicing, support generation, infill, build
  orientation, resin/FDM/SLS/metal workflows, print profiles, lattice
  structures, build simulation, material-shrinkage compensation, and print QA.
- **Manufacturing validation gate** — before a `toolpath` `DesignArtifact` may
  be `released`, it passes a validation gate that runs **material-removal
  simulation** (the path actually clears the intended stock), **tool collision
  detection** (the cutter does not strike the part, fixture, or clamps),
  **holder/gouge detection** (the tool holder clears the workpiece and the
  cutter does not gouge the finished surface), **remaining-stock analysis** (no
  uncut material is left), a **cycle-time estimate**, a **cost estimate**, and
  **tolerance stack checks**. A path that fails any of these is blocked from
  release. The gate also emits an inspection plan for the resulting
  `FabricationJob`.

## GIS and Geospatial — `@athena/gis`

The geospatial application surface.

- **Spatial data model** — vector and raster layers, coordinate reference
  systems and projections, geodetic calculations, topology, attributes, styling,
  metadata, and versioned geospatial projects.
- **Editing and analysis** — digitizing with snapping and topology rules;
  overlays, buffers, intersections, and joins; raster algebra; terrain analysis,
  hydrology, and viewsheds; routing and network analysis; and spatial
  statistics.
- **3D geospatial and CAD/BIM bridge** — terrain meshes, point clouds, LiDAR,
  photogrammetry, and city models; IFC/BIM interoperability, CAD overlays,
  survey control, georeferencing, and construction/site workflows.
- **Formats and services** — GeoJSON, Shapefile, GeoPackage, GeoTIFF, and
  LAS/LAZ files; WMS/WFS/WMTS/XYZ tile services; MBTiles; STAC-style catalogs;
  offline maps; and enterprise geodata publication.

## Kernel-Wide Features

The following capabilities are shared across all four surfaces of the Phase 136
kernel (CAD, EDA, CAM, and GIS). They are listed together because implementing
them once in a shared layer is more consistent and maintainable than each
surface re-inventing collaboration, scripting, and AI assistance independently.

- **Collaboration and data management** — versioned models with
  branching/merging, change review, comments and markups, permissions,
  approvals, release states, PLM-style item records, and audit trails. Release
  states map onto the `DesignArtifact` `draft → validated → released → archived`
  lifecycle.
- **Automation and scripting** — Python, Rust, and visual-graph APIs; parametric
  templates; batch conversion; validation scripts; design generators; and
  controlled (sandboxed) plugin execution.
- **AI assistance** — constraint repair (proposing fixes for over-constrained
  sketches), manufacturability suggestions, topology healing, feature
  recognition, drawing generation, design-space exploration, toolpath
  optimization, PCB rule assistance, and geospatial insight generation. AI
  assistance proposes; it does not auto-release artifacts.
- **Testing and validation** — golden geometry fixtures, solver regression
  suites, import/export conformance tests, Boolean stress tests, machining
  simulation tests, EDA design-rule suites, GIS projection tests, performance
  benchmarks, and reproducible sample projects.

## Implementation Status

There is no current `apps/athena/*` or `libs/athena/*` implementation; this
document is planned-scope only, spanning Phase 67 (maker/workshop) and Phase 136
(sovereign CAD/EDA/CAM/GIS kernel). When packages are created, each section
becomes the acceptance contract for its package, the Seshat ownership split must
be resolved first, and the architecture and specification documents must be
updated with concrete schemas, service contracts, and test gates.

Athena is also a named co-owner of Phase 144 (sovereign real-time visualization
renderers): the CAD studio's models feed `@neith/viz-livelink` for live CAD/BIM
synchronization into the `@neith/viz-*` renderers, and Athena consumes the
KeyShot-class product-visualization workflow for design review. Athena owns the
CAD data and change events; Neith owns the renderer.