95 lines
2.9 KiB
Markdown
95 lines
2.9 KiB
Markdown
|
# Function Anchor Template
|
||
|
|
|
||
|
|
Use this template to document any EVOLV class as a stable "logic truth" anchor.
|
||
|
|
|
||
|
|
## Mandatory File Layout (Required For Every Node)
|
||
|
|
- `.agents/function-anchors/<nodeName>/ANCHOR-<nodeName>.md`
|
||
|
|
- `.agents/function-anchors/<nodeName>/ANCHOR-<nodeName>.html`
|
||
|
|
- `.agents/function-anchors/<nodeName>/EVIDENCE-<nodeName>-tests.md`
|
||
|
|
- `nodes/<nodeName>/test/basic/*.test.js`
|
||
|
|
- `nodes/<nodeName>/test/integration/*.test.js`
|
||
|
|
- `nodes/<nodeName>/test/edge/*.test.js`
|
||
|
|
|
||
|
|
Any deviation from this layout must be treated as technical debt and resolved before closing the work item.
|
||
|
|
|
||
|
|
## 1) Connection Map (At a Glance)
|
||
|
|
- **Node type**:
|
||
|
|
- **Consumes from EVOLV nodes/topics**:
|
||
|
|
- **Publishes to EVOLV nodes/topics**:
|
||
|
|
- **Registers as child to**:
|
||
|
|
- **Accepts child registration from**:
|
||
|
|
- **Admin/UI endpoints**:
|
||
|
|
|
||
|
|
## 2) Unit Table (Always First Data Section)
|
||
|
|
| Signal/Field | Represents | Asset Type | Default Unit | Accepted Units | Source of Truth (file:line) | Produced By | Consumed By | Fallback/Degraded Behavior |
|
||
|
|
|---|---|---|---|---|---|---|---|---|
|
||
|
|
|
||
|
|
## 3) Class Identity
|
||
|
|
- **Class**:
|
||
|
|
- **Primary files**:
|
||
|
|
- **Runtime responsibility**:
|
||
|
|
- **Editor responsibility**:
|
||
|
|
|
||
|
|
## 4) Configuration Contract
|
||
|
|
| UI Field | Runtime Path | Default | Validation/Coercion | Behavior Impact | Source |
|
||
|
|
|---|---|---|---|---|---|
|
||
|
|
|
||
|
|
## 5) Input/Output Contract
|
||
|
|
### Input topics
|
||
|
|
| Topic | Payload schema | Handler | Side effects | Source |
|
||
|
|
|---|---|---|---|---|
|
||
|
|
|
||
|
|
### Output ports
|
||
|
|
| Port | Message type | Producer method | Typical consumers | Source |
|
||
|
|
|---|---|---|---|---|
|
||
|
|
|
||
|
|
### Admin endpoints
|
||
|
|
| Endpoint | Method | Purpose | Source |
|
||
|
|
|---|---|---|---|
|
||
|
|
|
||
|
|
## 6) Mode, State, and Control Model
|
||
|
|
- **Modes**:
|
||
|
|
- **Allowed actions by mode**:
|
||
|
|
- **Allowed sources by mode**:
|
||
|
|
- **Operational states for prediction**:
|
||
|
|
- **Sequence definitions**:
|
||
|
|
|
||
|
|
## 7) End-to-End Execution Flow
|
||
|
|
1. Constructor and initialization flow.
|
||
|
|
2. Registration and child wiring flow.
|
||
|
|
3. Input routing flow.
|
||
|
|
4. Tick/output emission flow.
|
||
|
|
5. Status update flow.
|
||
|
|
|
||
|
|
## 8) Full Function Inventory
|
||
|
|
| Function | Purpose | Reads | Writes | Calls | Emits/Returns | Failure/Fallback | Source | Covered by tests |
|
||
|
|
|---|---|---|---|---|---|---|---|---|
|
||
|
|
|
||
|
|
## 9) Calculations and Physical Semantics
|
||
|
|
- **Prediction paths** (flow, power, control).
|
||
|
|
- **Pressure selection order**.
|
||
|
|
- **Efficiency, CoG, and BEP distance calculations**.
|
||
|
|
- **Assumptions and plausibility constraints**.
|
||
|
|
|
||
|
|
## 10) Error Handling and Safeguards
|
||
|
|
- Validation guards.
|
||
|
|
- Warning/error paths.
|
||
|
|
- Availability-first behavior.
|
||
|
|
|
||
|
|
## 11) Test Evidence Matrix
|
||
|
|
| Test file | What is covered | Methods/contracts anchored |
|
||
|
|
|---|---|---|
|
||
|
|
|
||
|
|
## 12) Invariants (Anchor Truth)
|
||
|
|
- Non-negotiable behaviors this class must preserve.
|
||
|
|
|
||
|
|
## 13) Known Gaps / Risks
|
||
|
|
- Mismatches, TODOs, or technical debt observed in current implementation.
|
||
|
|
|
||
|
|
## 14) Change Checklist
|
||
|
|
- Required updates when logic changes:
|
||
|
|
- Code sections
|
||
|
|
- Contract docs
|
||
|
|
- Tests
|
||
|
|
- Example flows
|