standard: harden license timing threat model and legacy directory guidance

Author: Denis Yermakou

LICENSE

@@ -1,9 +1,21 @@
-Creative Commons Attribution 4.0 International Public License
+MIT License
 
-Documentation in this repository is intended to be licensed under Creative Commons
-Attribution 4.0 International (CC BY 4.0), unless otherwise stated.
+Copyright (c) 2026 Denis Yermakou / AxonOS
 
-You are free to share and adapt the material for any purpose, even commercially,
-provided that attribution is given and changes are indicated.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this documentation and associated files (the "Materials"), to deal
+in the Materials without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Materials, and to permit persons to whom the Materials are
+furnished to do so, subject to the following conditions:
 
-Full license text: https://creativecommons.org/licenses/by/4.0/legalcode
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Materials.
+
+THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR OTHER DEALINGS IN THE
+MATERIALS.

architecture/README.md

@@ -0,0 +1,11 @@
+# Architecture Directory
+
+Deprecated for normative reading.
+
+Canonical architecture-related material now lives in:
+
+- `standard/AOS-0001-system-boundary.md`
+- `standard/AOS-0008-ipc-and-timing-contract.md`
+- `standard/AOS-0010-reference-implementation-mapping.md`
+
+Files in this directory are retained only as redirects or historical navigation.

legal/README.md

@@ -0,0 +1,9 @@
+# Legal Directory
+
+Canonical disambiguation and attribution notes live here, but normative standard
+content lives in `standard/`.
+
+See also:
+
+- `legal/disambiguation.md`
+- `LICENSE`

rfcs/README.md

@@ -1,7 +1,8 @@
-# RFC Index
+# RFC Directory
 
-The AxonOS RFC process records engineering decisions and proposed changes to the standard.
+The canonical RFC repository is:
 
-Current RFC repository:
+https://github.com/AxonOS-org/axonos-rfcs
 
-- https://github.com/AxonOS-org/axonos-rfcs
+Standard-impacting RFCs should link back to the AOS artifacts in `standard/`.
+This directory is a navigation stub, not a second RFC source of truth.

standard/AOS-0008-ipc-and-timing-contract.md

@@ -1,72 +1,289 @@
 # AOS-0008 — IPC and Timing Contract
 
 Status: Draft 0.1 — pre-normative.  
-Audience: implementers, reviewers, safety assessors, researchers, and institutional partners.  
+Audience: kernel implementers, embedded systems engineers, safety reviewers, validation engineers, SDK authors, and hardware-in-the-loop test authors.  
 Normative force: draft language only until AxonOS Standard v1.0.
 
 ## 1. Purpose
 
-AOS-0008 defines draft expectations for bounded IPC and timing claims.
+This artifact defines the draft IPC and timing contract for AxonOS implementations.
 
-## 2. Scope
+AxonOS exists because BCI software cannot treat timing as a convenience metric.
+In a closed-loop neural system, timing violations can corrupt signal continuity,
+misalign intent windows, invalidate classifier state, or produce unsafe actuation
+behavior. Therefore a timing claim must be stated as a bounded claim under stated
+assumptions, not as an average or marketing number.
 
-This artifact defines draft standard semantics for AxonOS implementations. It is not a clinical protocol, regulatory approval, or certification claim. It exists to make implementation claims explicit, reviewable, and testable.
+This artifact defines the required shape of a real-time claim, the required
+shape of an IPC claim, deadline and response-time terminology, buffer and queue
+contract fields, failure behavior for overrun and deadline miss, evidence levels
+for timing claims, minimum conformance tests, and non-conformance examples.
 
-AxonOS repositories should reference this artifact when their README, API, tests, or documentation make claims in this area.
+Draft 0.1 does not define a final byte-level ABI. It defines the contract that
+future ABI and wire-format artifacts must satisfy.
 
+## 2. Timing vocabulary
 
-## 3. Timing claim form
+| Term | Meaning |
+|---|---|
+| `T_i` | Period of task `i` |
+| `D_i` | Relative deadline of task `i` |
+| `C_i` | Worst-case execution time of task `i` |
+| `R_i` | Worst-case response time of task `i` |
+| `U_i` | Utilisation contribution `C_i / T_i` |
+| `U_total` | Sum of admitted task utilisations |
+| `U_max` | Implementation-defined admission ceiling |
+| WCET | Worst-case execution time under stated assumptions |
+| WCRT | Worst-case response time under stated scheduling model |
+| IPC | Inter-process or inter-core communication mechanism |
+| overrun | Producer cannot enqueue because bounded capacity is exhausted |
+| deadline miss | Job completion occurs after its declared deadline |
 
-A timing claim should include deadline, bound, hardware context, workload, method, evidence level, and falsification threshold.
+A timing claim without a declared deadline and bound is not an AxonOS timing claim.
 
-## 4. IPC claim form
+## 3. Minimum real-time claim record
 
-An IPC claim should identify queue type, capacity, producer/consumer model, blocking behavior, overrun behavior, memory ordering, and unsafe-code surface.
+Every AxonOS timing claim should be expressible in the following form:
 
-## 5. Deadline miss behavior
+```text
+Claim:
+  component:
+  task/stage:
+  hardware:
+  clock:
+  period:
+  deadline:
+  WCET or WCRT bound:
+  scheduling model:
+  workload assumptions:
+  evidence level:
+  artifact:
+  falsification threshold:
+  limitations:
+```
 
-A safety-relevant implementation should document behavior on deadline miss.
+This format prevents mixing predicted, measured, and certified claims.
 
-## 6. Bounded behavior
+## 4. IPC contract record
 
-Bounded IPC means operation count and memory use are bounded under stated conditions.
+Every IPC mechanism used in an AxonOS real-time boundary should declare:
 
-## 7. Evidence mapping
+| Field | Required description |
+|---|---|
+| `name` | IPC mechanism name |
+| `role` | signal path, control path, diagnostic path, or application path |
+| `producer` | single producer, multiple producer, interrupt producer, DMA producer |
+| `consumer` | single consumer, task consumer, application consumer, inter-core consumer |
+| `capacity` | slot count or byte capacity |
+| `slot_size` | byte size of each slot, if fixed |
+| `alignment` | required alignment in bytes |
+| `endianness` | byte order for serialized fields |
+| `blocking_behavior` | wait-free, lock-free, bounded wait, blocking, or unknown |
+| `overrun_behavior` | reject, drop-newest, drop-oldest, backpressure, fault |
+| `memory_ordering` | ordering discipline for payload visibility |
+| `unsafe_surface` | unsafe code or equivalent low-level primitive |
+| `evidence_level` | evidence supporting the claim |
 
-Instruction-count derivations are L1. Runtime fixture measurements are L2. External GPIO or analyzer traces are L3.
+If a repository cannot fill this table, it should not claim AxonOS IPC conformance.
 
-## 8. Draft requirements
+## 5. Draft queue profile: SPSC-RT
 
-A draft implementation aligned with this artifact should satisfy:
+Draft 0.1 defines an initial queue profile named `SPSC-RT`.
 
-1. State deadlines and bounds for real-time claims.
-2. Document IPC capacity and overrun behavior.
-3. Document unsafe-code surface if any.
-4. State deadline miss behavior.
-5. Tag timing claims with evidence levels.
+`SPSC-RT` is a single-producer/single-consumer bounded queue suitable for a
+real-time signal path if all of the following hold:
 
-## 9. Minimum verification expectations
+1. capacity is fixed at compile time or initialization time;
+2. producer operation has bounded step count;
+3. consumer operation has bounded step count;
+4. no heap allocation occurs on the hot path;
+5. overrun behavior is explicit;
+6. payload visibility is governed by documented memory ordering;
+7. unsafe code surface is documented and tested;
+8. queue state can be reset or faulted safely.
 
-1. Tests cover queue invariants where applicable.
-2. Documentation states overrun behavior.
-3. Claims register includes timing entries.
-4. Hardware claims identify context.
-5. L3 claims include trace artifact references.
+`SPSC-RT` does not require a specific implementation. A ring buffer, static queue,
+or hardware mailbox may qualify if the contract is satisfied.
 
-## 10. Non-conformance examples
+## 6. Draft packet layout requirements
 
-The following are examples of non-conforming or misleading use:
+A future stable ABI may define byte-level packet formats. Until then, any IPC
+packet or event frame crossing an AxonOS boundary should document at minimum:
 
-1. Real-time claim with only average latency.
-2. IPC claim without capacity.
-3. Lock-free claim without evidence.
-4. Deadline miss behavior undocumented.
-5. Measured claim with no artifact.
+| Field | Requirement |
+|---|---|
+| magic/version | identifies frame family and version |
+| frame_type | typed event, control, consent, safety, diagnostic, etc. |
+| length | payload length in bytes |
+| sequence | monotonic counter or sequence number if ordered |
+| timestamp | monotonic timestamp or declared absence |
+| source | component or node identity |
+| flags | delivery, safety, or compatibility flags |
+| payload | typed payload, schema-defined |
+| integrity | checksum, MAC, signature, or declared absence |
 
-## 11. Open issues
+Endianness must be explicit. Alignment requirements must be explicit. Reserved
+fields must have defined default values.
 
-Draft 0.1 intentionally leaves some details unresolved. Future revisions may add machine-readable schemas, test vectors, stricter conformance profiles, and implementation-version mappings. Any promotion from draft text to normative text must be recorded through the governance process.
+## 7. Example frame envelope
 
-## 12. Summary
+Draft 0.1 does not freeze ABI bytes, but a future frame envelope should be able
+to express the following conceptual layout:
 
-This artifact defines one part of the AxonOS Standard boundary. It should be read together with AOS-0000 through AOS-0011 and the repository-level `CONFORMANCE.md`, `VALIDATION.md`, and `GOVERNANCE.md` documents.
+```text
+0                   1                   2                   3
+0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-------------------------------+-------------------------------+
+| magic/version                 | frame_type                    |
++-------------------------------+-------------------------------+
+| header_len                    | payload_len                   |
++-------------------------------+-------------------------------+
+| sequence_low                                                  |
++---------------------------------------------------------------+
+| sequence_high                                                 |
++---------------------------------------------------------------+
+| timestamp_low                                                 |
++---------------------------------------------------------------+
+| timestamp_high                                                |
++---------------------------------------------------------------+
+| source_id                                                     |
++---------------------------------------------------------------+
+| flags                         | reserved                      |
++-------------------------------+-------------------------------+
+| payload ...                                                   |
++---------------------------------------------------------------+
+| integrity ...                                                 |
++---------------------------------------------------------------+
+```
+
+The exact byte width of each field is not normative in Draft 0.1. The normative
+requirement is that future byte-level definitions must not leave versioning,
+length, ordering, timestamp semantics, or integrity semantics implicit.
+
+## 8. Deadline miss behavior
+
+A safety-relevant implementation must document behavior on deadline miss.
+
+Acceptable responses may include reject current output, enter degraded mode,
+trigger backpressure, clear affected queue, enter safe idle, disable stimulation,
+emit safety event, fault session, or log transition.
+
+Unacceptable default behavior includes silently delivering stale intent, silently
+skipping safety state update, continuing stimulation with stale classification,
+hiding the deadline miss from audit trail, or converting hard deadlines into
+best-effort scheduling without documentation.
+
+## 9. Overrun behavior
+
+Overrun behavior must be explicit.
+
+| Policy | Meaning | Safety note |
+|---|---|---|
+| reject-new | producer returns error; existing data preserved | often safest for control paths |
+| drop-new | incoming item discarded | must be audited |
+| drop-old | oldest item discarded | dangerous for signal continuity |
+| backpressure | producer slows or blocks | must be bounded |
+| fault | system enters fault state | appropriate for safety-critical paths |
+
+For a safety-critical neural signal path, silent drop-old behavior is presumptively
+non-conformant unless justified by a bounded safety case.
+
+## 10. Priority inversion and blocking
+
+If the IPC or timing path can block, the implementation must document maximum
+blocking time, priority inheritance or ceiling protocol, scheduler interaction,
+interrupt masking duration, critical-section duration, and deadlock avoidance
+argument.
+
+A system with unbounded blocking in the critical neural path cannot claim hard
+real-time AxonOS alignment.
+
+## 11. Timing jitter
+
+Jitter claims must distinguish release jitter, completion jitter, transport
+jitter, scheduler jitter, measurement jitter, clock drift, and timestamp
+quantization.
+
+A claim such as "low jitter" is insufficient. The claim must state what jitter
+is being measured and how.
+
+## 12. Evidence mapping
+
+| Evidence level | Timing evidence example |
+|---|---|
+| L0 | design intent or architecture sketch |
+| L1 | analytical bound, instruction-count derivation, model check |
+| L2 | measured on development fixture |
+| L3 | externally instrumented trace: GPIO, logic analyzer, oscilloscope |
+| L4 | independent reproduction or review |
+| L5 | formal regulatory/certification evidence |
+
+An L1 timing proof does not become L3 because it is precise. L3 requires an
+external measurement artifact.
+
+## 13. Minimum test expectations
+
+A draft AxonOS timing implementation should provide tests or artifacts for queue
+capacity enforcement, overrun behavior, enqueue/dequeue invariants, memory
+ordering or equivalent visibility argument, deadline miss reporting, timestamp
+monotonicity, reset behavior, fault behavior after corrupted queue state, no heap
+allocation on declared hot path, and documentation of unsafe surface.
+
+## 14. Conformance requirements
+
+A draft AxonOS IPC/timing implementation should satisfy:
+
+1. timing claims include deadline and bound;
+2. IPC capacity is documented;
+3. IPC overrun behavior is documented;
+4. blocking behavior is documented;
+5. memory ordering or visibility semantics are documented;
+6. unsafe or low-level surface is documented;
+7. deadline miss behavior is documented;
+8. evidence level is declared;
+9. L3 claims include trace artifact references;
+10. hidden best-effort conversion is prohibited.
+
+## 15. Non-conformance examples
+
+The following are non-conforming or misleading: real-time claim with only average
+latency, queue with undocumented capacity, lock-free claim without implementation
+evidence, wait-free claim with hidden retry loop, L3 claim without trace artifact,
+silent deadline miss, silent drop-old overrun in signal path, unbounded mutex in
+critical neural path, IPC packet with no version field, and serialized event with
+unknown endianness.
+
+## 16. Release checklist for an IPC/timing claim
+
+Before an AxonOS repository publishes an IPC/timing claim, the maintainer should
+verify:
+
+- the hardware target is named;
+- the clock source is named;
+- the scheduler or execution model is named;
+- queue capacity is named;
+- overrun behavior is named;
+- deadline miss behavior is named;
+- blocking behavior is named;
+- memory ordering or equivalent visibility semantics are named;
+- the claim appears in the claims register;
+- the evidence level is stated;
+- the artifact is linked;
+- the falsification threshold is stated.
+
+This checklist is intentionally strict because real-time BCI claims are easy to
+overstate and difficult to repair after publication.
+
+## 17. Open issues
+
+Draft 0.1 leaves unresolved: stable ABI for typed intent events, canonical packet
+byte layout, canonical capability descriptor layout, shared-memory mailbox
+profile, multi-producer queue profile, inter-core timing profile, conformance
+test vectors, and hardware trace artifact schema.
+
+## 18. Summary
+
+AxonOS timing claims must be bounded, falsifiable, and evidence-tagged.
+
+The standard does not forbid experimentation. It forbids presenting best-effort
+behavior as hard real-time evidence.