estimation

Empirical resource estimation for ticket-bound URI processes. The package
measures real process trees and learns conservative scheduling envelopes from
append-only history. Runtime ownership remains in semcod; Subactor retains
authority to decide whether a Process URI may execute.

What is measured

• wall-clock duration and exit outcome;
• user/system CPU time and effective CPU cores;
• peak aggregate RSS for the process tree;
• read/write bytes where the operating system permits access;
• maximum process count, host capacity profile and sample count.

Raw command arguments, environment values, stdout, stderr and secret material
are never persisted. URI query strings and fragments are removed before a URI
is stored or used as the statistical key. Only the program name and an argv
SHA-256 fingerprint are retained.

Install

python -m pip install -e .

Measure a caller-authorized command

estimation run \
  --process-uri 'testql://project/suite/query/run' \
  --ticket PLF-1234 \
  --store ~/.local/state/semcod-estimation/process-samples.jsonl \
  --events ~/.local/state/semcod-estimation/process-events.jsonl \
  -- python -m pytest -q

The command's exit code is returned by estimation. Failed runs remain in
history and affect success_rate, but resource percentiles are based on
successful samples so an immediate startup failure does not look artificially
cheap.

Observe an existing process tree

estimation observe \
  --pid 12345 \
  --duration 30 \
  --process-uri 'control://automation/watchdog/command/run' \
  --ticket PLF-1234

Observation is bounded by duration and does not signal, restart or otherwise
control the target process.

Report and estimate

estimation validate --store ~/.local/state/semcod-estimation/process-samples.jsonl
estimation report --store ~/.local/state/semcod-estimation/process-samples.jsonl
estimation estimate \
  --store ~/.local/state/semcod-estimation/process-samples.jsonl \
  --process-uri 'testql://project/suite/query/run' \
  --quantity 20 \
  --parallelism 4

Reports expose p50, p90, mean, standard deviation, success rate and confidence.
Confidence is none, low, medium or high based on successful sample
count. Workload estimates multiply conservative p90 values by quantity and
parallelism to support queue admission and host-capacity planning.

Subactor integration

1. Subactor resolves a ticket and authorized Process URI.
2. The executor wraps the actual command with estimation run, or observes a
   service PID with estimation observe.
3. Samples are appended to the node-local state store; a parallel hash-chained
   wellmanifest.logs/event/v1 stream records the measurement outcome.
4. The scheduler queries estimation://history/query/estimate before admitting
   similar work and compares p90 CPU, RSS and duration with host capacity.
5. Missing or low-confidence history is a planning uncertainty, never implicit
   authorization to run a process.

The package adopts wellmanifest/new-project and wellmanifest/logs.