File size: 18,025 Bytes
bf8ad08
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
"""A study runner that keeps training, executed query outcomes and claims distinct."""

from dataclasses import asdict, dataclass, field
import json
import math
from numbers import Integral
from pathlib import Path
import platform
import time

import numpy as np
import scipy
import torch
from torch.nn import functional as F

from aether.config import ModelConfig
from aether.environments.stress import TASK_FAMILIES, create_world, stress_expert_batch
from aether.evidence.promotion import promotion_decision
from aether.evidence.receipts import write_receipt, write_source_snapshot
from aether.evidence.statistics import paired_summary
from aether.kernel.runtime import TissueModel
from aether.kernel.conformance import check_transport_conformance


PROTOCOLS = ('scalar', 'scalar_matched', 'vector', 'attention', 'phase', 'modes', 'wave')
INTERVENTIONS = ('zero_gain', 'erase_packets', 'shuffle_phase', 'random_phase')


@dataclass
class StudyConfig:
    seeds: list[int] = field(default_factory=lambda: [11, 29, 47])
    protocols: list[str] = field(default_factory=lambda: list(PROTOCOLS))
    updates: int = 40
    batch_size: int = 8
    evaluation_episodes: int = 24
    learning_rate: float = 0.003
    delay: int = 3
    horizon: int = 9
    retention_delay: int = 5
    retention_margin: float = 0.05
    min_confirmatory_seeds: int = 30
    model: dict = field(default_factory=dict)
    task_family: str = 'straight'

    def __post_init__(self):
        for key in ('updates', 'batch_size', 'evaluation_episodes', 'delay', 'horizon',
                    'retention_delay', 'min_confirmatory_seeds'):
            value = getattr(self, key)
            if isinstance(value, bool) or not isinstance(value, Integral) or value < 1:
                raise ValueError(f'{key} must be a positive integer')
        if self.min_confirmatory_seeds < 10:
            raise ValueError('min_confirmatory_seeds must be at least 10')
        if not isinstance(self.seeds, list) or not self.seeds:
            raise ValueError('seeds must be a nonempty list')
        if any(isinstance(s, bool) or not isinstance(s, Integral) or not 0 <= s <= 9999 for s in self.seeds):
            raise ValueError('seeds must be unique integers in [0,9999]')
        if len(set(self.seeds)) != len(self.seeds):
            raise ValueError('independent training seeds must be unique')
        if (not isinstance(self.protocols, list) or not self.protocols
                or any(p not in PROTOCOLS for p in self.protocols)
                or len(set(self.protocols)) != len(self.protocols)
                or 'scalar' not in self.protocols or 'wave' not in self.protocols):
            raise ValueError('protocols must be unique known names including scalar and wave')
        if (isinstance(self.learning_rate, bool) or not isinstance(self.learning_rate, (int, float))
                or not math.isfinite(self.learning_rate) or self.learning_rate <= 0):
            raise ValueError('learning_rate must be finite and positive')
        if (isinstance(self.retention_margin, bool) or not isinstance(self.retention_margin, (int, float))
                or not math.isfinite(self.retention_margin) or not 0 <= self.retention_margin <= 1):
            raise ValueError('retention_margin must be finite in [0,1]')
        if self.retention_delay <= self.delay or self.horizon < self.delay + 2:
            raise ValueError('retention delay must exceed support delay; horizon must permit goal completion')
        if self.task_family not in TASK_FAMILIES:
            raise ValueError(f'task_family must be one of {TASK_FAMILIES}')
        # Validate the selected world's horizon before creating a run directory.
        create_world(self.task_family, seed=0, delay=self.delay, horizon=self.horizon)
        if self.updates * self.batch_size >= 100_000:
            raise ValueError('support episode budget exceeds disjoint seed block')
        if self.evaluation_episodes >= 1000:
            raise ValueError('evaluation_episodes must be below 1000 for disjoint seed blocks')
        if not isinstance(self.model, dict):
            raise ValueError('model must be an object')
        model = ModelConfig(**self.model)
        if model.input_dimension != 12 or model.action_count != 7:
            raise ValueError('navigation requires 12 observations and 7 actions')


def write_json(path: Path, value):
    path.write_text(json.dumps(value, indent=2, allow_nan=False) + '\n', encoding='utf-8')


def episode_seeds(seed: int, count: int, retention: bool = False) -> list[int]:
    return [(2_000_000_000 if retention else 1_000_000_000) + seed * 1000 + i for i in range(count)]


def evaluate(model: TissueModel, seeds: list[int], *, delay: int, horizon: int,

             intervention: str = 'none', disturbance_seed: int = 0,

             task_family: str = 'straight') -> dict:
    digest = model.state_digest()
    was_training = model.training
    model.eval()
    records = []
    with torch.no_grad():
        for episode_seed in seeds:
            world = create_world(task_family, seed=episode_seed, delay=delay, horizon=horizon)
            state = model.initial_state(1)
            actions, total_reward = [], 0.0
            while not world.done:
                observation = torch.from_numpy(world.observe()[None])
                logits, state = model.step(observation, state, intervention=intervention,
                                           disturbance_seed=disturbance_seed + episode_seed + world.timestep)
                if not torch.isfinite(logits).all() or not torch.isfinite(state).all():
                    raise RuntimeError('query produced nonfinite neural state')
                action = int(logits.argmax(-1).item())
                _, reward, _ = world.step(action)
                actions.append(action)
                total_reward += reward
            records.append({'seed': episode_seed, 'success': world.success,
                            'return': round(total_reward, 8), 'actions': actions,
                            'final_position': world.position.tolist()})
    model.train(was_training)
    if model.state_digest() != digest:
        raise RuntimeError('query mutated learned parameters or persistent buffers')
    return {'success_rate': float(np.mean([r['success'] for r in records])),
            'mean_return': float(np.mean([r['return'] for r in records])),
            'executed_steps': sum(len(r['actions']) for r in records),
            'episode_seeds': list(seeds), 'episodes': records}


def train_one(config: StudyConfig, protocol: str, seed: int, output: Path) -> dict:
    model = TissueModel(ModelConfig(**config.model), protocol=protocol, seed=seed)
    conformance = check_transport_conformance(model)
    if not conformance['valid']:
        raise RuntimeError('tensor transport did not match packet reference')
    initial_digest = model.state_digest()
    optimizer = torch.optim.AdamW(model.parameters(), lr=config.learning_rate)
    curve, executed = [], 0
    started = time.perf_counter()
    for update in range(config.updates):
        # Each seed owns a nonoverlapping support block well below query blocks.
        support_seeds = [seed * 100_000 + update * config.batch_size + i
                         for i in range(config.batch_size)]
        batch = stress_expert_batch(support_seeds, task_family=config.task_family,
                                    delay=config.delay, horizon=config.horizon)
        observation = torch.from_numpy(batch['observations'])
        targets = torch.from_numpy(batch['actions'])
        mask = torch.from_numpy(batch['mask'])
        optimizer.zero_grad(set_to_none=True)
        logits = model(observation, disturbance_seed=seed * 1000 + update)
        loss = F.cross_entropy(logits[mask], targets[mask])
        if not torch.isfinite(loss):
            raise RuntimeError('nonfinite support loss')
        loss.backward()
        norm = torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0, error_if_nonfinite=True)
        optimizer.step()
        executed += batch['executed_steps']
        curve.append({'update': update + 1, 'loss': float(loss.detach()),
                      'gradient_norm': float(norm),
                      'support_action_accuracy': float((logits[mask].argmax(-1) == targets[mask]).float().mean())})
    train_seconds = time.perf_counter() - started
    trained_digest = model.state_digest()
    evaluation = evaluate(model, episode_seeds(seed, config.evaluation_episodes),
                          delay=config.delay, horizon=config.horizon, task_family=config.task_family)
    retention_horizon = config.horizon + config.retention_delay - config.delay
    retention = evaluate(model, episode_seeds(seed, config.evaluation_episodes, retention=True),
                         delay=config.retention_delay, horizon=retention_horizon,
                         task_family=config.task_family)
    interventions = {}
    if protocol == 'wave':
        for name in INTERVENTIONS:
            interventions[name] = evaluate(model, episode_seeds(seed, config.evaluation_episodes),
                                            delay=config.delay, horizon=config.horizon,
                                            intervention=name, disturbance_seed=seed + 91_000,
                                            task_family=config.task_family)
    filename = f'checkpoints/{protocol}-{seed}.pt'
    (output / 'checkpoints').mkdir(exist_ok=True)
    checkpoint = {'schema': 'aether.checkpoint.v1', 'model_config': asdict(model.config),
                  'protocol': protocol, 'seed': seed, 'state_dict': model.state_dict(),
                  'trained_digest': trained_digest, 'evaluation': evaluation,
                  'retention': retention, 'interventions': interventions,
                  'delay': config.delay, 'horizon': config.horizon,
                  'retention_delay': config.retention_delay,
                  'retention_horizon': retention_horizon,
                  'task_family': config.task_family,
                  'intervention_disturbance_seed': seed + 91_000}
    torch.save(checkpoint, output / filename)
    replay = replay_checkpoint(output / filename)
    if not replay['valid']:
        raise RuntimeError(f'checkpoint failed exact local replay: {filename}')
    count = sum(p.numel() for p in model.parameters())
    return {'protocol': protocol, 'seed': seed, 'initial_digest': initial_digest,
            'trained_digest': trained_digest, 'query_immutable': model.state_digest() == trained_digest,
            'checkpoint': filename, 'replay_valid': replay['valid'], 'parameter_count': count,
            'train_seconds': train_seconds, 'executed_support_steps': executed,
            'resources': model.resource_metrics(), 'transport_conformance': conformance,
            'training_updates': config.updates, 'training_curve': curve,
            'evaluation': evaluation, 'retention': retention, 'interventions': interventions}


def replay_checkpoint(path: Path) -> dict:
    torch.set_num_threads(1)
    torch.use_deterministic_algorithms(True)
    saved = torch.load(path, map_location='cpu', weights_only=True)
    if saved.get('schema') != 'aether.checkpoint.v1':
        raise ValueError('unsupported checkpoint schema')
    model = TissueModel(ModelConfig(**saved['model_config']), saved['protocol'], saved['seed'])
    model.load_state_dict(saved['state_dict'], strict=True)
    task_family = saved.get('task_family', 'straight')
    evaluation = evaluate(model, saved['evaluation']['episode_seeds'],
                          delay=saved['delay'], horizon=saved['horizon'], task_family=task_family)
    retention = evaluate(model, saved['retention']['episode_seeds'],
                         delay=saved['retention_delay'], horizon=saved['retention_horizon'],
                         task_family=task_family)
    interventions = {name: evaluate(model, outcome['episode_seeds'],
                                    delay=saved['delay'], horizon=saved['horizon'],
                                    intervention=name,
                                    disturbance_seed=saved['intervention_disturbance_seed'],
                                    task_family=task_family)
                     for name, outcome in saved['interventions'].items()}
    expected_names = set(INTERVENTIONS) if saved['protocol'] == 'wave' else set()
    valid = (evaluation == saved['evaluation'] and retention == saved['retention']
             and interventions == saved['interventions'] and set(interventions) == expected_names
             and model.state_digest() == saved['trained_digest'])
    return {'valid': valid, 'evaluation': evaluation, 'retention': retention,
            'interventions': interventions, 'state_digest': model.state_digest()}


def run_study(config: StudyConfig, output: Path, progress=None) -> dict:
    config.__post_init__()  # reject mutation of a previously validated config
    output = Path(output)
    output.mkdir(parents=True, exist_ok=False)
    torch.set_num_threads(1)
    torch.use_deterministic_algorithms(True)
    write_json(output / 'config.json', asdict(config))
    source_root = Path(__file__).resolve().parents[2]
    # Snapshot and fingerprint share one allowlist and the exact archived bytes.
    fingerprint = write_source_snapshot(source_root, output / 'source-snapshot.zip')
    metadata = {'source_fingerprint': fingerprint,
                'environment': {'python': platform.python_version(), 'platform': platform.platform(),
                                'torch': str(torch.__version__), 'numpy': np.__version__,
                                'scipy': scipy.__version__, 'torch_threads': 1},
                'reproducibility_scope': 'exact local replay on recorded software and hardware'}
    runs = []
    for seed in config.seeds:
        for protocol in config.protocols:
            if progress:
                progress(f'training {protocol}, seed {seed}')
            run = train_one(config, protocol, seed, output)
            runs.append(run)
            write_json(output / 'partial-results.json', {'metadata': metadata, 'runs': runs})
            if progress:
                progress(f"{protocol} seed {seed}: success {run['evaluation']['success_rate']:.3f}, "
                         f"loss {run['training_curve'][0]['loss']:.3f} -> {run['training_curve'][-1]['loss']:.3f}")
    by_protocol = {name: sorted((r for r in runs if r['protocol'] == name), key=lambda r: r['seed'])
                   for name in config.protocols}
    scores = lambda name, split='evaluation': [r[split]['success_rate'] for r in by_protocol[name]]
    comparisons = {name: (scores('wave'), scores(name)) for name in config.protocols if name != 'wave'}
    promotion = promotion_decision(comparisons, retention_candidate=scores('wave', 'retention'),
                                   retention_baseline=scores('scalar', 'retention'),
                                   retention_margin=config.retention_margin,
                                   replay_valid=all(r['replay_valid'] for r in runs),
                                   integrity_valid=all(r['query_immutable'] for r in runs),
                                   resources_comparable=False,
                                   min_confirmatory_seeds=config.min_confirmatory_seeds)
    # Missing predeclared controls cannot be waived by narrowing the CLI arm list.
    if set(config.protocols) != set(PROTOCOLS):
        promotion['promoted'] = False
        promotion['status'] = 'rejected'
        promotion['reasons'].append('full predeclared seven-protocol comparison was not executed')
    aggregates = {name: {'mean_success': float(np.mean(scores(name))),
                          'mean_retention_success': float(np.mean(scores(name, 'retention'))),
                          'parameter_count': by_protocol[name][0]['parameter_count'],
                          'mean_train_seconds': float(np.mean([r['train_seconds'] for r in by_protocol[name]]))}
                  for name in config.protocols}
    task_limitations = {
        'straight': 'Disjoint query seeds draw from the same six fixed goal tasks; there are no held-out geometries.',
        'distraction': ('Disjoint query seeds resample six fixed goals with seeded sensory distractors; '
                        'there are no held-out geometries or demonstrated phase-filtering advantage.'),
        'waypoint': ('Disjoint query seeds resample 30 fixed ordered direction pairs; the second direction '
                     'is cued again after the first waypoint. There are no held-out route families.'),
    }
    result = {'schema': 'aether.study.v1', 'status': 'exploratory', 'metadata': metadata,
              'config': asdict(config), 'runs': runs, 'aggregates': aggregates,
              'paired_effects': {name: paired_summary(*pair) for name, pair in comparisons.items()},
              'promotion': promotion,
              'limitations': ['Synthetic delayed-cue imitation task, not reinforcement learning or general intelligence.',
                              'Training examples and update counts are matched; measured compute is not established equivalent.',
                              'Packet-reference impairments are separately tested; this training study uses clean tensor transport.',
                              task_limitations[config.task_family],
                              'Longer-delay evaluation is a retention proxy, not a sequential catastrophic-forgetting study.']}
    write_json(output / 'results.json', result)
    from aether.observatory import render_report
    render_report(result, output / 'index.html')
    write_receipt(output, metadata=metadata)
    return result