Documentation
¶
Overview ¶
Package consolidate is the pure core of the offline self-optimization cycle (SPEC-ADDITIONS §18.4): harvest closed arcs, mine recurring checkable tasks and assign each a stable held-out split, then reflect-and-gate a bounded candidate edit on a strict held-out improvement. It performs no I/O and reads no clock — the staging id is the content hash of the proposal, so a cycle is fully reproducible. The command shell (cmd/sleep) supplies the artifact, the harvested arcs, and the optimizer's proposed learned text, and writes staging from the returned Cycle; it makes no decision of its own.
Scoring is deterministic without a live worker: a mined task is a checkable assertion about the guiding artifact (e.g. "the artifact should mention this failure class"). A split's score is the mean hard rule-judge score over its tasks, so learned text that makes more assertions pass scores strictly higher on the held-out selection split and the ratchet accepts it — while an empty or harmful candidate does not (mirrored by harness.SelfTest's negative control).
Index ¶
- Constants
- func Calibration(records []evidence.Record) calibration.Report
- func Propose(signals []Signal, cfg Config) string
- func ProposePrompt(signals []Signal, artifact string, cfg Config) string
- func SlowGuidance(long Longitudinal) string
- type CommonClass
- type Config
- type Cycle
- type Diagnostic
- type Longitudinal
- type Mode
- type ModeKind
- type Reflection
- type Signal
- type Split
- type SplitScore
- type Task
Constants ¶
const DefaultCommonCoverage = 0.5
DefaultCommonCoverage is the arc-fraction floor for CommonClasses: a class must recur in more than half the harvested arcs to count as a common approach.
const DefaultReplicationRuns = 3
DefaultReplicationRuns is how many independent seeded partitions the fresh- replication eval scores a candidate over (§18.2) — enough for ≥2 independent passing runs to earn an ELEVATE.
Variables ¶
This section is empty.
Functions ¶
func Calibration ¶
func Calibration(records []evidence.Record) calibration.Report
Calibration measures how well the sleep optimizer's projected candidate score (NewScore) predicts whether the candidate was actually kept — the reliability of the loop's own judgment, the complement to the significance its verdict already gets from stats. Each cycle that proposed a candidate is one sample: the projected score is the prediction (already in [0,1] from gate.SelectScore) and "kept" is the realized outcome. A no-candidate baseline cycle records the same variable in both OldScore and NewScore, so NewScore == OldScore is a same-variable equality (not a float tolerance) that skips it. Pure.
func Propose ¶
Propose is the mock optimizer: it renders the reflected modes as guidance bullets for the protected region — failure modes ("Guard against") first so they win the edit budget, then success modes ("Keep doing"). The budget (the learning rate) clips the ranked remainder. An empty result means there was nothing to learn.
func ProposePrompt ¶
ProposePrompt renders the relay prompt for an agent-driven proposal (§18): the ranked reflection modes (what recurred), the artifact's current protected region, and the instruction to reply with the one bounded edit to that region. It is the relay counterpart to the mock Propose — the agent supplies the edit and may consult `adh tool run skillsaw-eval` for dimension scores, while adh's held-out gate still decides whether the reply is kept. It is pure.
func SlowGuidance ¶
func SlowGuidance(long Longitudinal) string
SlowGuidance renders durable cross-cycle guidance from the longitudinal categories (§18.3, SkillOpt's slow update) — deterministic, no backend.
Types ¶
type CommonClass ¶
type CommonClass struct {
Class string `json:"class"`
Kind ModeKind `json:"kind"`
Coverage float64 `json:"coverage"`
}
CommonClass is a lesson class that recurs across a fraction of the harvested arcs — a systemic pattern, not a one-arc quirk. Kind is whether it shows up in the arcs' failure or success signals; Coverage is the fraction of arcs exhibiting it. It is the arc-coverage complement to Mode, which ranks classes by raw recurrence count.
func CommonClasses ¶
func CommonClasses(signals []Signal, minCoverage float64) []CommonClass
CommonClasses mines the lesson classes that recur across more than minCoverage of the harvested arcs — the systemic patterns the arcs consistently hit — separately for their failure and success signals. Unlike Reflect's Mode.Count (raw instances, which one noisy arc can inflate), coverage counts each class once per arc, so it surfaces what most arcs do, not what one arc did loudly. Sorted by descending coverage, then kind, then class. Pure.
type Config ¶
type Config struct {
Marker string `json:"marker"`
EditBudget int `json:"edit_budget"`
SizeRatio float64 `json:"size_ratio"`
Metric gate.Metric `json:"metric"`
MixedWeight float64 `json:"mixed_weight"`
Round int `json:"round"`
}
Config carries the §18.5 levers: the protected-region marker (only that region is machine-edited), the edit budget (the learning rate — how many classes become guidance per round), the size ratio (a candidate may not exceed ratio × the current artifact), and the gate metric (how a hard/soft score pair projects onto one comparable number, ported from SkillOpt's select_gate_score).
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the §18.5 defaults: the ADH:LEARNED marker, an edit budget of 4, a 1.5× size bound, and the hard gate metric.
type Cycle ¶
type Cycle struct {
Signals []Signal `json:"signals"`
Tasks []Task `json:"tasks"`
Baseline float64 `json:"baseline"`
Candidate float64 `json:"candidate"`
BaselineSoft float64 `json:"baseline_soft"`
CandidateSoft float64 `json:"candidate_soft"`
Decision gate.Result `json:"decision"`
Proposed string `json:"proposed,omitempty"`
StagingID string `json:"staging_id,omitempty"`
Diags []Diagnostic `json:"diagnostics"`
Longitudinal Longitudinal `json:"longitudinal"`
SlowGuidance string `json:"slow_guidance,omitempty"`
Verdict verdict.Verdict `json:"verdict,omitempty"`
Replication verdict.Verdict `json:"replication,omitempty"`
Records []evidence.Record `json:"records"`
}
Cycle is the pure outcome of one consolidation pass: the harvested signals, the mined tasks, the baseline and candidate selection scores, the gate decision, the proposed artifact (set only on acceptance), the candidate's content-addressed staging id (set whenever a candidate was scored, so a rejected one can be remembered), the per-task diagnostics, and the evidence records to append. Records carry no timestamp — the shell stamps them.
func Plan ¶
func Plan( artifact, learned string, arcs []adh.Arc, rejected map[string]bool, cfg Config, ) (Cycle, error)
Plan runs one consolidation cycle purely. Given the current artifact, the optimizer's proposed learned text, the harvested arcs, and the set of previously rejected candidate hashes, it mines tasks, scores the baseline and the candidate over the selection split, and accepts only a strict held-out improvement (§18.2). It stages a proposal (Proposed/StagingID set) only on acceptance; every outcome carries diagnostics and an evidence record.
type Diagnostic ¶
type Diagnostic struct {
Task string `json:"task"`
Split Split `json:"split"`
Hard float64 `json:"hard"`
Soft float64 `json:"soft"`
Reason string `json:"reason"`
}
Diagnostic is one held-out task's self-explanation (§18.6): its hard score and the reason, so a cycle that accepts nothing is not a black box.
type Longitudinal ¶
type Longitudinal struct {
Improved int `json:"improved"`
Regressed int `json:"regressed"`
StableSuccess int `json:"stable_success"`
PersistentFail int `json:"persistent_fail"`
Lines []string `json:"lines,omitempty"`
}
Longitudinal compares a task's outcome under the previous artifact against the candidate (§18.3, SkillOpt's slow-update summary): how many improved, regressed, stayed green, or kept failing. Regressed is the highest priority, so Lines leads with regressions ahead of persistent failures.
func Categorize ¶
func Categorize(prev, curr []Diagnostic) Longitudinal
Categorize compares each task's hard outcome under the previous artifact against the candidate, counting improved/regressed/stable/persistent-fail (SkillOpt's slow-update summary). Lines leads with regressions — the highest priority — then persistent failures, capped for brevity.
type Mode ¶
type Mode struct {
Class string `json:"class"`
Kind ModeKind `json:"kind"`
Count int `json:"count"`
}
Mode is one reflected class and how often it recurred — the recurrence Count is the ranking key the edit budget clips against (rank_and_select).
type ModeKind ¶
type ModeKind string
ModeKind is whether a reflected class is a failure or a success mode.
type Reflection ¶
Reflection is the optimizer's read of the harvested history (§18.3): failure modes to avoid and success modes to reinforce, each ranked by recurrence. Failure modes win a conflict — a class that is both is kept only as a failure.
func Reflect ¶
func Reflect(signals []Signal) Reflection
Reflect reads the harvested signals into ranked failure and success modes (§18.3): each class is ranked by recurrence (rank_and_select), and a class that recurs as both a failure and a success is kept only as a failure — failure modes win the conflict.
type Signal ¶
type Signal struct {
Arc string `json:"arc"`
Resolution string `json:"resolution,omitempty"`
Failures []string `json:"failures,omitempty"`
Successes []string `json:"successes,omitempty"`
}
Signal is one harvested closed arc's learnable content: the misses to avoid and the affirmative outcomes to reinforce.
**Provenance is planned and deliberately absent today**, so the shape is recorded here rather than left to whoever adds the second source. Mining sessions the harness never governed is a heuristic, and its output would reach Mine, which builds the held-out splits -- so a wrong inference would not add noise, it would move the objective the gate hill-climbs. When a second source arrives, Signal gains a provenance field whose **zero value means unknown**: a signal that does not say where it came from must not be read as arc-derived, so a consumer added later gets the conservative reading by forgetting rather than the permissive one. Only arc-derived signals may enter the splits; other provenance feeds Reflect and the §11 lesson candidates, where the temporal and human gates already stand between a false positive and a change.
A separate type for foreign signals was the alternative, and this is the cheaper half of the same guarantee: one accretion path, one place that says no.
func Harvest ¶
Harvest reduces closed arcs to their learnable signals; open arcs are skipped.
Closed arcs are the only source, which bounds what the loop can learn to work the harness itself drove. Widening it is planned and gated -- see Signal on why a second source must carry provenance before it reaches Mine.
type Split ¶
type Split string
Split is the held-out partition a mined task belongs to.
Split values partition mined tasks. Selection is held out for acceptance; test is reported on but never used to accept; train may grow from recalled or synthetic tasks (§18.4). A task's split is stable across cycles.
func SplitFor ¶
SplitFor maps a task id to its stable split by hashing the id, so a real task's split never changes across cycles and no clock or randomness is used.
func SplitForSeed ¶
SplitForSeed is SplitFor over an independent partition selected by seed, so the same mined tasks can be re-partitioned N ways for a fresh-replication eval (§18.2) — each seed is an independent held-out selection set, and no clock or randomness is used. Seed 0 is the canonical partition SplitFor uses.
type SplitScore ¶
SplitScore is a split's aggregate rule-judge score — the mean hard and mean soft over its tasks, ported from SkillOpt's aggregate_scores (compute_score).
Source Files