Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,19 @@ The three honesty levels (R2):
| --- | --- | --- |
| `UC-WEB-01` | `build` | The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure. |

## performance-theorems

| ID | Level | Statement |
| --- | --- | --- |
| `UC-PERF-02` | `build` | For every input length n, the settled frame of Uorc.Performance is no larger than the raw frame and no larger than a coded kernel candidate, and the raw frame is two length varints of at most 10 bytes each, the n input bytes and 41 fixed bytes, so no frame of one object exceeds n + 61 bytes (archiveBound), and a stream of k such frames is within n + 61 * k bytes; the native client keeps the same rule and the same constants. |
| `UC-PERF-03` | `build` | For every list of trials, the trial the portfolio keeps (Uorc.Performance best) is no larger in bytes than any coded trial in the list (bestNoLargerThanEvery), so a portfolio archive is no larger than the archive of any strategy it scheduled. |
| `UC-PERF-04` | `build` | A step is one model input evaluated for one coded bit. For every profile word the input count lies between 3 and 24 (17 context bits, 3 fixed inputs, 2 for each of the short-match and repeat features), a frame of n bytes costs 8 * n * inputs steps, and for every frame kind (raw, reference, ncm, ncm from a named state) decode takes at most 192 steps per modelled byte (decodeStepsBound); the full profile costs 192 steps per byte and the v0.3 profile 160. The measure counts model inputs, not machine time. |
| `UC-PERF-05` | `build` | A trial carries its defect, the count of bytes at which its decode differs from the input. Admission fails every trial with a nonzero defect, keeping never raises a defect above its operands', and the trial kept from any admitted list has defect 0 (bestOfAdmittedIsExact): whatever codec point or named model state produced a trial, it can change the archive's size and never its meaning. |
| `UC-PERF-06` | `build` | A candidate dominates an incumbent when it is no larger in bytes and no larger in steps, and its gain is the drop in bytes plus steps. The gain never exceeds the drop in cost (dominanceLowersCost), no trial gains over itself, gains compose (a positive gain of a over b and of b over c gives at least their sum of a over c), and a positive gain implies no growth in bytes or in steps: dominance is a strict partial order, so consolidating winners cannot cycle. |
| `UC-PERF-07` | `build` | A trial abandoned at a bound is modelled as a trial of at most the bound's bytes. For every list of trials and every raw length, the portfolio of trials abandoned at the raw length settles to the same size as the portfolio of complete trials (boundedPortfolioSettlesTheSame), and a trial no smaller than one already kept changes neither the kept bytes nor the kept steps (skippedTrial theorems): a search that stops a candidate once it cannot win, or skips one known to be no smaller, writes an archive of the same size for fewer compress steps. |
| `UC-PERF-08` | `build` | Choosing by fewer bytes and then fewer steps, from the raw frame and any list of trials, keeps a trial that is no later in that order than every trial in the list and than the raw frame (chosenIsLeast, chosenIsNoWorseThanRaw), has exactly the size the bytes-only rule settles to (chosenKeepsTheSize), and is dominated by no trial it is no later than (leastIsUndominated); a trial no earlier than the kept one changes nothing (excludedTrial theorems). The rule lowers decode steps on byte ties at no cost in size. The released client breaks byte ties by schedule order until its model export adopts this rule. |
| `UC-PERF-09` | `build` | The potential of a codec point is its bytes plus its steps. Consolidating a candidate into an incumbent lowers the potential by exactly the candidate's gain (consolidationSpendsItsGain), which is positive exactly when the candidate dominates, and over any sequence of candidates the potential never rises (potentialNeverRises). The potential is a natural number, so an engine that consolidates only dominating candidates never regresses and consolidates at most as many times as its first potential. |

## product-interfaces

| ID | Level | Statement |
Expand Down Expand Up @@ -168,3 +181,11 @@ The three honesty levels (R2):
| `UC-INT-05` | `build` | `build_evidence` | `not_measured` | Source-owned completed-view and continuous publication proofs derive the actual chosen-profile digest and emitted-image reads, discharging canonical driver termination and OwnedHash control/cleanup lifetime for both explicit format identities and arbitrary finite source input. Initial source-layout correspondence and full product acceptance remain separate consumer obligations. |
| `UC-NEU-01` | `build` | `kernel_theorem` | `not_measured` | The ncm coder's plasticity is stated as the Prism neuromorphic standard in Uorc.Neuromorphic, with kernel-checked bounds: every mixer weight stays within plus or minus 2^22 under the bounded Hebbian rule, potentiation never lowers and depression never raises a weight, the plasticity lies between 24 and 128 per 65536 (128 at the first byte, 24 in the limit), one bit's weight change is at most 16376 and every product fits a 32-bit lane, a context slot never steps past its gap to the coded bit and consolidates at count 127, and every probability-map point stays within 16 bits; the native coder reads the model's constants. |
| `UC-WEB-01` | `build` | `build_evidence` | `not_measured` | The Pages client is generated from and conforms to its Prism product model in Uorc.Page: stakeholders, features with their calls and acceptance cases, journeys, the page's UML state machine, operations, fields, controls, examples, error hints, sections, usage, links and quality measures. The generated page holds exactly the modeled elements, and a real browser walks every journey, takes every modeled transition, checks every control's enabled state in every state it reaches and holds every gated quality measure. |
| `UC-PERF-02` | `build` | `kernel_theorem` | `not_measured` | For every input length n, the settled frame of Uorc.Performance is no larger than the raw frame and no larger than a coded kernel candidate, and the raw frame is two length varints of at most 10 bytes each, the n input bytes and 41 fixed bytes, so no frame of one object exceeds n + 61 bytes (archiveBound), and a stream of k such frames is within n + 61 * k bytes; the native client keeps the same rule and the same constants. |
| `UC-PERF-03` | `build` | `kernel_theorem` | `not_measured` | For every list of trials, the trial the portfolio keeps (Uorc.Performance best) is no larger in bytes than any coded trial in the list (bestNoLargerThanEvery), so a portfolio archive is no larger than the archive of any strategy it scheduled. |
| `UC-PERF-04` | `build` | `kernel_theorem` | `not_measured` | A step is one model input evaluated for one coded bit. For every profile word the input count lies between 3 and 24 (17 context bits, 3 fixed inputs, 2 for each of the short-match and repeat features), a frame of n bytes costs 8 * n * inputs steps, and for every frame kind (raw, reference, ncm, ncm from a named state) decode takes at most 192 steps per modelled byte (decodeStepsBound); the full profile costs 192 steps per byte and the v0.3 profile 160. The measure counts model inputs, not machine time. |
| `UC-PERF-05` | `build` | `kernel_theorem` | `not_measured` | A trial carries its defect, the count of bytes at which its decode differs from the input. Admission fails every trial with a nonzero defect, keeping never raises a defect above its operands', and the trial kept from any admitted list has defect 0 (bestOfAdmittedIsExact): whatever codec point or named model state produced a trial, it can change the archive's size and never its meaning. |
| `UC-PERF-06` | `build` | `kernel_theorem` | `not_measured` | A candidate dominates an incumbent when it is no larger in bytes and no larger in steps, and its gain is the drop in bytes plus steps. The gain never exceeds the drop in cost (dominanceLowersCost), no trial gains over itself, gains compose (a positive gain of a over b and of b over c gives at least their sum of a over c), and a positive gain implies no growth in bytes or in steps: dominance is a strict partial order, so consolidating winners cannot cycle. |
| `UC-PERF-07` | `build` | `kernel_theorem` | `not_measured` | A trial abandoned at a bound is modelled as a trial of at most the bound's bytes. For every list of trials and every raw length, the portfolio of trials abandoned at the raw length settles to the same size as the portfolio of complete trials (boundedPortfolioSettlesTheSame), and a trial no smaller than one already kept changes neither the kept bytes nor the kept steps (skippedTrial theorems): a search that stops a candidate once it cannot win, or skips one known to be no smaller, writes an archive of the same size for fewer compress steps. |
| `UC-PERF-08` | `build` | `kernel_theorem` | `not_measured` | Choosing by fewer bytes and then fewer steps, from the raw frame and any list of trials, keeps a trial that is no later in that order than every trial in the list and than the raw frame (chosenIsLeast, chosenIsNoWorseThanRaw), has exactly the size the bytes-only rule settles to (chosenKeepsTheSize), and is dominated by no trial it is no later than (leastIsUndominated); a trial no earlier than the kept one changes nothing (excludedTrial theorems). The rule lowers decode steps on byte ties at no cost in size. The released client breaks byte ties by schedule order until its model export adopts this rule. |
| `UC-PERF-09` | `build` | `kernel_theorem` | `not_measured` | The potential of a codec point is its bytes plus its steps. Consolidating a candidate into an incumbent lowers the potential by exactly the candidate's gain (consolidationSpendsItsGain), which is positive exactly when the candidate dominates, and over any sequence of candidates the potential never rises (potentialNeverRises). The potential is a natural number, so an engine that consolidates only dominating candidates never regresses and consolidates at most as many times as its first potential. |
1 change: 1 addition & 0 deletions crates/uorc/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ pub mod archive;
pub mod chunk;
mod frame;
pub mod ncm;
pub mod performance;
pub mod portfolio;
mod store;
pub mod tree;
Expand Down
246 changes: 246 additions & 0 deletions crates/uorc/src/performance.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
//! The performance vocabulary of the Prism model (`Uorc.Performance`), as the
//! native client computes it: the step measure, the codec point and the
//! choice rules (least in bytes then steps, dominance, consolidation).
//!
//! A **step** is one model input evaluated for one coded bit. It is exact and
//! deterministic, and it is read from a frame's header alone: a raw frame
//! costs one step per output byte (the copy), a reference frame costs none
//! (its bytes were produced once already), and an ncm frame costs eight bits
//! times the inputs its profile word keeps, per output byte, with or without
//! the x86 filter. The constants are the model's; `tests/performance.rs`
//! reads them from the module text.

use crate::frame::{Info, Representation};
use crate::ncm;
use sha2::{Digest, Sha256};

/// Coded bits per output byte.
pub const BITS_PER_BYTE: u64 = 8;
/// Inputs every ncm profile evaluates beside its contexts: the match model's
/// two and the bias.
pub const FIXED_INPUTS: u32 = 3;
/// Inputs each optional model (short match, repeat distance) adds.
pub const FEATURE_INPUTS: u32 = 2;
/// Context bits of a profile word.
pub const CONTEXT_BITS: u32 = 17;
/// The most inputs any profile evaluates: 17 contexts, the fixed 3, two features.
pub const MAX_INPUTS: u32 = CONTEXT_BITS + FIXED_INPUTS + 2 * FEATURE_INPUTS;
/// The bound of `Uorc.Performance.decodeStepsBound`: no frame costs more
/// steps per output byte than this (the full model).
pub const MAX_STEPS_PER_BYTE: u64 = BITS_PER_BYTE * MAX_INPUTS as u64;
/// The bit of a codec point's profile word that says the frame is coded over
/// the x86 filter (the strategy table's encoding: bits 0-19 the ncm profile,
/// bit 31 the filter). The filter changes the bytes a frame codes, not its steps.
pub const POINT_X86: u32 = 1 << 31;
/// Domain tag of a codec point's identity.
pub const CODEC_POINT_TAG: &[u8] = b"uorc/codec-point/1";

/// Model inputs an ncm frame coded under `profile` evaluates per bit.
pub fn inputs(profile: u32) -> u32 {
(profile & ((1 << CONTEXT_BITS) - 1)).count_ones()
+ FIXED_INPUTS
+ FEATURE_INPUTS * u32::from(profile & ncm::F_SHORT != 0)
+ FEATURE_INPUTS * u32::from(profile & ncm::F_REP != 0)
}

/// Steps to decode `n` output bytes of a frame of this representation and
/// profile word; `None` for a representation the model states no measure for
/// (the ulz decoders kept for earlier archives, and searched programs).
pub fn steps(representation: Representation, profile: Option<u32>, n: u64) -> Option<u64> {
match representation {
Representation::Raw => Some(n),
Representation::Reference => Some(0),
Representation::Ncm | Representation::NcmX86 => {
Some(BITS_PER_BYTE * u64::from(inputs(profile.unwrap_or(ncm::V03))) * n)
}
Representation::Ulz | Representation::UlzKernel | Representation::Program => None,
}
}

/// [`steps`] of the frame a header describes.
pub fn frame_steps(info: &Info) -> Option<u64> {
steps(info.representation, info.ncm_profile, info.output_len)
}

/// A point of the codec space: which decoder basis, profile word, consolidated
/// model state and lane count code a frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CodecPoint {
/// The basis identity the frame names (the export's library), zeros when
/// the frame is self-contained.
pub basis: [u8; 32],
/// The ncm profile word, with [`POINT_X86`] set when the frame is coded
/// over the x86 filter; 0 when the frame applies no ncm decoder.
pub profile: u32,
/// κ of the consolidated model state the frame starts from, zeros for none.
pub state: [u8; 32],
/// Lanes the frame is coded in (1 for a single stream).
pub lanes: u32,
}

impl CodecPoint {
/// The point of the frame a header describes (no state, one lane).
pub fn of(info: &Info) -> CodecPoint {
CodecPoint {
basis: info.basis.unwrap_or([0; 32]),
profile: info.ncm_profile.unwrap_or(0)
| if info.representation == Representation::NcmX86 {
POINT_X86
} else {
0
},
state: [0; 32],
lanes: 1,
}
}

/// κ of the point: SHA-256 over the tag, the basis, the profile word
/// (little-endian), the state and the lane count (little-endian).
pub fn kappa(&self) -> [u8; 32] {
let mut h = Sha256::new();
h.update(CODEC_POINT_TAG);
h.update(self.basis);
h.update(self.profile.to_le_bytes());
h.update(self.state);
h.update(self.lanes.to_le_bytes());
h.finalize().into()
}
}

/// κ of a corpus: SHA-256 over `uorc/corpus/1` and, for each object in order,
/// its name length (u32 LE), name, SHA-256 and length (u64 LE).
pub fn corpus_kappa<'a>(objects: impl IntoIterator<Item = (&'a str, [u8; 32], u64)>) -> [u8; 32] {
let mut h = Sha256::new();
h.update(b"uorc/corpus/1");
for (name, digest, len) in objects {
h.update((name.len() as u32).to_le_bytes());
h.update(name.as_bytes());
h.update(digest);
h.update(len.to_le_bytes());
}
h.finalize().into()
}

/// A coded trial as the model's choice rules see it: its archive bytes and
/// its decode steps (`Uorc.Performance.Trial.coded`, without the defect).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Trial {
/// Archive bytes.
pub bytes: u64,
/// Decode steps.
pub steps: u64,
}

impl Trial {
/// `cost`: the potential the engine lowers, bytes plus steps.
pub fn cost(self) -> u64 {
self.bytes + self.steps
}
}

/// `gainOf`: how far `candidate` dominates `incumbent` (no larger in bytes
/// and in steps): the drop in cost, 0 when it does not dominate.
pub fn gain(candidate: Trial, incumbent: Trial) -> u64 {
if candidate.bytes <= incumbent.bytes && candidate.steps <= incumbent.steps {
incumbent.cost() - candidate.cost()
} else {
0
}
}

/// `lexGap`: 0 exactly when `a` is no later than `c` in the order "fewer
/// bytes, then fewer steps".
pub fn lex_gap(a: Trial, c: Trial) -> u64 {
a.bytes.saturating_sub(c.bytes)
+ a.steps
.saturating_sub(c.steps)
.min(1)
.saturating_sub(c.bytes.saturating_sub(a.bytes))
}

/// `pick`: the kept trial after `head` is considered. A failed trial (`None`)
/// changes nothing; a coded one replaces the kept trial when it has fewer
/// bytes, or the same bytes and fewer steps.
pub fn pick(head: Option<Trial>, kept: Trial) -> Trial {
match head {
Some(h) if h.bytes < kept.bytes || (h.bytes == kept.bytes && h.steps < kept.steps) => h,
_ => kept,
}
}

/// `chosen`: the trial kept from the raw frame and the scheduled trials
/// (`chosenIsLeast`: least in bytes, then steps; `leastIsUndominated`).
pub fn chosen(raw: Trial, trials: &[Option<Trial>]) -> Trial {
trials
.iter()
.rev()
.fold(raw, |kept, &head| pick(head, kept))
}

/// `consolidate`: the incumbent after `candidate` is decided: the candidate
/// when it dominates with a positive gain, else the incumbent
/// (`consolidationSpendsItsGain`: the cost drops by exactly the gain).
pub fn consolidate(candidate: Trial, incumbent: Trial) -> Trial {
if gain(candidate, incumbent) > 0 {
candidate
} else {
incumbent
}
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn steps_follow_the_profile_word() {
assert_eq!(inputs(ncm::V03), 20);
assert_eq!(inputs(ncm::FULL), MAX_INPUTS);
assert_eq!(steps(Representation::Raw, None, 10), Some(10));
assert_eq!(steps(Representation::Reference, None, 10), Some(0));
assert_eq!(steps(Representation::Ncm, Some(ncm::FULL), 10), Some(1920));
assert_eq!(
steps(Representation::NcmX86, Some(ncm::FULL), 10),
Some(10 * MAX_STEPS_PER_BYTE)
);
for profile in [ncm::V03, ncm::FULL, 1, 0x7ffff] {
assert!(inputs(profile) <= MAX_INPUTS);
}
}

#[test]
fn a_codec_point_is_named_by_all_its_coordinates() {
let p = CodecPoint {
basis: [1; 32],
profile: ncm::FULL,
state: [0; 32],
lanes: 1,
};
assert_ne!(p.kappa(), CodecPoint { lanes: 2, ..p }.kappa());
assert_ne!(
p.kappa(),
CodecPoint {
state: [2; 32],
..p
}
.kappa()
);
assert_ne!(
p.kappa(),
CodecPoint {
profile: ncm::V03,
..p
}
.kappa()
);
assert_ne!(
p.kappa(),
CodecPoint {
profile: ncm::FULL | POINT_X86,
..p
}
.kappa()
);
assert_eq!(p.kappa(), p.kappa());
}
}
Loading
Loading