ECSS Simulation Modelling — Epoch Time (space-systems/ecss/e4008-epoch-time)
Use when the task is the epoch time scale of ECSS-E-ST-40-08C clause
5.4.1 -- a schedule entry that names the absolute instant it is due
at, rather than an offset from the start of the run, and the one
normative item that fixes how the simulator resolves it.
Domain quick reference
- Simulation time counts from the start of the run. Epoch time names
an instant on an absolute scale. An entry on the epoch scale is
resolved by subtracting the epoch value that corresponds to
simulation time zero, and nothing else about it changes.
- The arithmetic is trivial and the failures are not. Every way this
goes wrong is a declaration or a representation problem, which is
why the clause exists at all.
- Both scales are integer nanoseconds. A double holds every integer
only up to about nine quadrillion, which a mission-length interval
in nanoseconds passes, so a float instant is refused rather than
rounded into something that looks fine.
- The epoch at simulation time zero has to be declared. Treating an
absent reference as zero does not fail; it silently shifts every
entry in the schedule by the whole mission epoch, and the run looks
plausible throughout.
- The conversion is exact and reversible. A resolved entry can always
be restated on the scale it was written on, which is what lets an
operator check a schedule against the mission timeline it came
from.
- An instant already in the past is a finding, not a nuisance. It is
the usual symptom of a schedule written against the wrong epoch,
and silently discarding it removes the only evidence.
- A repeating entry is different from a single-shot one here. The
single shot is gone once its instant has passed; the repeater steps
forward whole periods to the first occurrence at or after the
instant the schedule is being resolved for.
Workflow
- Validate both instants as exact integer nanosecond counts inside
the 64-bit range, refusing a float and refusing a boolean, which
Python would otherwise widen into a zero or a one.
- Refuse the conversion outright when the epoch at simulation time
zero has not been declared, rather than defaulting it.
- Subtract to get the base simulation time, guarding the result
against overflow of the nanosecond range.
- Record the declared disposition of that base time against the
clock now -- in the future, exactly now, or already past -- and
raise a finding for the past case before any repeat handling.
- Resolve the occurrence that will actually run: the base time for a
single shot that has not passed, or the base stepped forward by
whole periods for a repeater, using integer arithmetic so the
result is exact on every platform.
- Order a set of entries by occurrence, break ties by declared
order, name the entries with no occurrence left rather than
dropping them silently, and close with the findings.
Pitfalls
- Holding either scale in a float. Nanoseconds over a mission exceed
what a double represents exactly, so the entry drifts by a margin
that grows with the mission and no test at small numbers sees it.
- Defaulting an undeclared epoch reference to zero. Every entry moves
by the mission epoch at once, so the schedule stays internally
consistent and looks correct until it is compared with an external
timeline.
- Discarding an entry whose instant has already passed. The schedule
then resolves clean against the wrong epoch, and the missing entry
is only noticed when the event it was supposed to trigger does not
happen.
- Treating a repeating entry like a single shot. It is not gone once
its base instant passes; it has a next occurrence, and dropping it
removes a periodic activity from the whole run.
- Computing the step count for a repeater in floating point. The
division lands a hair either side of a whole number on different
platforms, so the occurrence jumps a full period depending on where
it ran.
- Ordering tied entries by name. Two entries due at the same instant
keep their declared order; sorting them by name changes the
execution order of a schedule that was never edited.
Behavior contract (gate 3)
The nanosecond validation, epoch-to-simulation conversion and its
exact inverse, the overflow guard, the already-past disposition, the
integer repeat-period stepping and the tie-stable occurrence ordering
are exercised by the gate 3 contract test:
scripts/test_e4008_epoch_time.py against
scripts/e4008_epoch_time_logic.py (stdlib unittest, offline). Run:
python3 scripts/test_e4008_epoch_time.py
Compliance
- ECSS standards are freely downloadable (ESA); cite the source and
paraphrase per standards-map.yaml.
- compliance: STANDARDS-REF, gated: false.
1---2name: e4008-epoch-time3description: "Convert an epoch-scale schedule entry onto simulation time under ECSS-E-ST-40-08C clause 5.4.1, the single normative item that clause places on an entry written at an absolute instant. Use when a schedule mixes epoch instants with simulation-time offsets and the simulator has to decide when each entry actually fires: subtracting the declared epoch at simulation time zero, refusing a float nanosecond count and an undeclared epoch reference, keeping the conversion exactly reversible, reporting an instant the run has already passed instead of dropping it, and stepping a repeating entry to its first occurrence at or after the resolution instant. Trigger: ecss, e-st-40-08-simulation-modelling-scope, e4008-epoch-time, schedule-epoch-time-entry, epoch-to-simulation-time-conversion, epoch-reference-declaration, epoch-entry-already-past, epoch-entry-repeat-period."4license: Apache-2.05compliance: STANDARDS-REF6standards:7 - id: ecss8 reference-only: true9gated: false10domain: space-systems11pack: space-systems12compatibility: "agentskills.io SKILL.md; any SKILL.md host (Claude Code, Hermes, OpenClaw)"13metadata:14 source: https://skillmd.com/skills/ashfordeou/e4008-epoch-time15 domain: space-systems16 subdomain: ecss17 tags: [ecss, e-st-40-08-simulation-modelling-scope, e4008-epoch-time, schedule-epoch-time-entry, epoch-to-simulation-time-conversion, epoch-reference-declaration, epoch-entry-already-past, epoch-entry-repeat-period]18 version: 0.1.019 author: Aero Agent Skills20---2122# ECSS Simulation Modelling — Epoch Time (space-systems/ecss/e4008-epoch-time)2324Use when the task is the epoch time scale of ECSS-E-ST-40-08C clause255.4.1 -- a schedule entry that names the absolute instant it is due26at, rather than an offset from the start of the run, and the one27normative item that fixes how the simulator resolves it.2829## Domain quick reference3031- Simulation time counts from the start of the run. Epoch time names32 an instant on an absolute scale. An entry on the epoch scale is33 resolved by subtracting the epoch value that corresponds to34 simulation time zero, and nothing else about it changes.35- The arithmetic is trivial and the failures are not. Every way this36 goes wrong is a declaration or a representation problem, which is37 why the clause exists at all.38- Both scales are integer nanoseconds. A double holds every integer39 only up to about nine quadrillion, which a mission-length interval40 in nanoseconds passes, so a float instant is refused rather than41 rounded into something that looks fine.42- The epoch at simulation time zero has to be declared. Treating an43 absent reference as zero does not fail; it silently shifts every44 entry in the schedule by the whole mission epoch, and the run looks45 plausible throughout.46- The conversion is exact and reversible. A resolved entry can always47 be restated on the scale it was written on, which is what lets an48 operator check a schedule against the mission timeline it came49 from.50- An instant already in the past is a finding, not a nuisance. It is51 the usual symptom of a schedule written against the wrong epoch,52 and silently discarding it removes the only evidence.53- A repeating entry is different from a single-shot one here. The54 single shot is gone once its instant has passed; the repeater steps55 forward whole periods to the first occurrence at or after the56 instant the schedule is being resolved for.5758## Workflow59601. Validate both instants as exact integer nanosecond counts inside61 the 64-bit range, refusing a float and refusing a boolean, which62 Python would otherwise widen into a zero or a one.632. Refuse the conversion outright when the epoch at simulation time64 zero has not been declared, rather than defaulting it.653. Subtract to get the base simulation time, guarding the result66 against overflow of the nanosecond range.674. Record the declared disposition of that base time against the68 clock now -- in the future, exactly now, or already past -- and69 raise a finding for the past case before any repeat handling.705. Resolve the occurrence that will actually run: the base time for a71 single shot that has not passed, or the base stepped forward by72 whole periods for a repeater, using integer arithmetic so the73 result is exact on every platform.746. Order a set of entries by occurrence, break ties by declared75 order, name the entries with no occurrence left rather than76 dropping them silently, and close with the findings.7778## Pitfalls7980- Holding either scale in a float. Nanoseconds over a mission exceed81 what a double represents exactly, so the entry drifts by a margin82 that grows with the mission and no test at small numbers sees it.83- Defaulting an undeclared epoch reference to zero. Every entry moves84 by the mission epoch at once, so the schedule stays internally85 consistent and looks correct until it is compared with an external86 timeline.87- Discarding an entry whose instant has already passed. The schedule88 then resolves clean against the wrong epoch, and the missing entry89 is only noticed when the event it was supposed to trigger does not90 happen.91- Treating a repeating entry like a single shot. It is not gone once92 its base instant passes; it has a next occurrence, and dropping it93 removes a periodic activity from the whole run.94- Computing the step count for a repeater in floating point. The95 division lands a hair either side of a whole number on different96 platforms, so the occurrence jumps a full period depending on where97 it ran.98- Ordering tied entries by name. Two entries due at the same instant99 keep their declared order; sorting them by name changes the100 execution order of a schedule that was never edited.101102## Behavior contract (gate 3)103104The nanosecond validation, epoch-to-simulation conversion and its105exact inverse, the overflow guard, the already-past disposition, the106integer repeat-period stepping and the tie-stable occurrence ordering107are exercised by the gate 3 contract test:108scripts/test_e4008_epoch_time.py against109scripts/e4008_epoch_time_logic.py (stdlib unittest, offline). Run:110python3 scripts/test_e4008_epoch_time.py111112## Compliance113114- ECSS standards are freely downloadable (ESA); cite the source and115 paraphrase per standards-map.yaml.116- compliance: STANDARDS-REF, gated: false.