v0.3 milestone: lock decay equations, versioned calibration artifact, ADR-006 affect

[mazze93]

Goal

Ship v0.3 as a gated software milestone. Owner: @mazze93.

Three evidence layers. Do not collapse them.

Layer	Question	Source of truth	Release gate?
Implementation invariants	Does Swift implement the declared equations and safety boundaries?	Deterministic unit/property tests (I2–I7)	Yes
Calibration evaluation	Are parameter choices reproducible and safe to ship?	Versioned decay-params.json + harness	Yes
Falsification study	Do the mechanisms explain useful differences in real usage?	Frozen FALSIFICATION.md + append-only ledger	No

FALSIFICATION.md supersedes I2–I7 naming where they overlap empirically (P1≈I3, P3≈I2, P4≈I5). It does not replace code-level invariant tests, artifact validation, migration, or privacy work.

P1–P4 failure is a research finding. Report it. Open an ADR review. Do not silently retune thresholds. Do not block a software release unless a safety-critical behavioral claim is invalidated.

Empirical validation dependency

FALSIFICATION.md is frozen before the first ledger event and governs a 30-day N-of-1 study. Its P1–P4 outcomes are not CI or release gates.

• Unit/property tests prove code implements the declared model.
• Calibration tests prove artifact loading and reproducibility.
• P1–P4 test the model's empirical claims in real usage.
• Any falsified prediction is reported, retained, and triggers an ADR review; it must not be silently “fixed” by changing thresholds or exclusions.

Freeze before data (do this first):

git add FALSIFICATION.md
git commit -m "research: preregister 30-day falsification study"
git tag -a falsification-v1 -m "Frozen preregistration before ledger start"
git push origin main --follow-tags
git rev-parse HEAD

Stamp SHA/tag into the file only if zero events.jsonl records exist. After the first event: no amendments; deviations only in declared extension / relabel / outcome sections.

Depends on PR #28 (append-only journal) before the first study event.

Ownership

Workstream	Owner	Verify
Freeze + tag FALSIFICATION.md	@mazze93	tag falsification-v1 precedes first event
Append-only ledger (PR #28)	@mazze93	verify command fails on reorder/alter/delete
Analysis lock (scripts/analyze_falsification.py + lockfile)	@mazze93	fixture-ledger tests; single invocation
Invariants I2–I7 + evidence cap	@mazze93	CI unit + property
Calibration artifact lifecycle	@mazze93	schema + repro CI
State migration / version fields	@mazze93	load old fixtures
ADR-006 + affect flag	@mazze93	privacy tests, off = no writes

1. Calibration operationalization

Treat calibration/decay-params.json as a versioned, validated release artifact, not an editable config.

Schema: schemaVersion, artifactVersion, lambdaBase ≥ 0, errorDecayAmplifier ≥ 0, rotLambdaAmplifier ≥ 0, lighthouseFloorCeiling in (0,1], provenance (fixtureHash, harnessVersion, gitSha, generatedAt, objectiveScore), previousArtifactVersion.

Runtime: reject malformed/out-of-range; fall back to last validated artifact else compiled defaults; non-sensitive diagnostics only; active version observable.

CI: harness must reproduce within tolerance. Rollback via calibration/history/. No leftover CircuitConstants literals for λ, γ, rot amp, or c₀.

2. Code oracles (I2–I7) — still required

These prove implementation, not empirical truth. Fixtures declare μ̄, α, β, Rot, e(s), passCount, Δt.

ID	Empirical twin	Assertion
I2 floor↓ under error	P3 (code-side)	floor = μ̄ · c₀ falls under sustained high e
I3 high-ε dies faster	P1 (code-side)	fixed Rot, e_hi > e_lo ⇒ W_hi < W_lo
I4 early amp halved	—	passCount 19/20/21; γ_eff = 0.5γ if <20
I5 rot ⊥ ε	P4 (code-side)	each term moves W alone
I6 neighbor β only	—	neighbor μ̄ unchanged; β ↑
I7 evidence cap	P3 ossification	no update at/above cap without user reset

Boundaries: e=0/1, Rot=0/saturated, pass 19/20/21, cap exact/+1. Property tests randomize Rot and ε independently. Float tol 1e-9 relative unless documented.

3. Chain of custody (before first event)

Ledger schema (events.jsonl)

{
  "schemaVersion": 1,
  "eventID": "uuid",
  "seq": 1,
  "previousHash": "sha256:...",
  "recordHash": "sha256:...",
  "timestamp": "2026-08-20T13:42:11Z",
  "synapseID": "stable-pseudonymous-id",
  "eventType": "outcome",
  "priorMeanBefore": 0.8,
  "observedUtility": 0.25,
  "predictionError": 0.55,
  "rotScore": 0.31,
  "weightBefore": 0.74,
  "weightAfter": 0.63,
  "calibrationVersion": "sha256:...",
  "implementationCommit": "git-sha"
}

Stable pseudonymous IDs only. Never free-text context, prompts, filenames, or raw labels.

Utility coding (locked before data)

• 0.0 = no useful result, abandoned, or net rework
• 0.5 = partially useful; meaningful manual correction
• 1.0 = useful; retained or completed intended task
• Code within 24h. Do not revise after seeing model metrics.
• Uncertain → 0.5 + reason code: unclear | delayed-benefit | mixed-result | external-blocker

Missing / ambiguous observations

• Missing fields → drop the event from P1–P4 numerators; keep the day as a zero-activity day if no valid events remain.
• Ambiguous utility → 0.5 + reason code. Never impute 0.0 or 1.0.
• Duplicate eventID or hash-chain break → analysis fails closed; do not repair the ledger in place.
• Clock skew / out-of-order timestamps → fail verification; do not sort silently.

Analysis lock (commit before window opens)

python3 scripts/analyze_falsification.py \
  --ledger data/events.jsonl \
  --preregistration FALSIFICATION.md \
  --output results/falsification-v1.json \
  --seed 20260819

Required in-tree: script, requirements.lock or uv.lock, documented bootstrap replicate count + seed, fixture-ledger tests that each falsification branch is reachable, machine-readable results schema.

Ledger integrity

Hash chain is evidence of accidental corruption or undeclared alteration — not tamper-proof against a motivated author with write access.

• Monotonic seq, previousHash / recordHash
• One write path; append-only perms where supported
• Verify command fails on reorder / alter / delete
• Verification result included in analysis output
• No cloud-sync or telemetry of event contents by default

4. State migration

Persist calibrationArtifactVersion on session/synapse records. Lazy recompute on next observe. Downgrade: readable, no silent re-decay, surface mismatch. Document in INTEGRATION.md.

5. ADR-006 affect (ADR before code)

Number 006. Non-goal: no prior nudge. Threat model + TTL + fail-closed privacy tests as previously specified. Flag default off.

6. v0.3 Definition of Done (software)

• FALSIFICATION.md committed + tag falsification-v1 before first events.jsonl line
• Ledger schema + utility rubric + missing-observation rule committed
• Analysis script + lockfile committed; fixture tests prove each P-fail branch
• PR feat(journal): enforceable append-only log — guard, archive, distilled lessons #28 merged or equivalent append-only verify path exists
• Calibration artifact schema-validated, versioned, provenance-stamped, loaded at runtime
• Invalid/missing artifacts fail safe + non-sensitive diagnostics
• I2–I7 deterministic (+ property for I5)
• Evidence-cap + user-gated-update tests
• ADR-006 + affect flag off / zero persistence
• CI: unit, property, calibration repro, privacy — not P1–P4 outcomes
• Release notes name behavioral changes + artifactVersion

7. Execution order

1. Land + tag FALSIFICATION.md (custody sections included; no events yet)
2. Merge/review PR feat(journal): enforceable append-only log — guard, archive, distilled lessons #28; no first study event until verify-path exists
3. Commit analysis script + lockfile + fixture-ledger tests
4. I2–I7 tests against current equations
5. Calibration schema/harness/fallback
6. Migration version fields
7. ADR-006, then flagged affect
8. CI + release notes

Out of scope (v0.4+)

Set-valued priors, embedding rot scorer, multi-lighthouse, affect-driven prior updates, treating P1–P4 as green-build requirements.