@trillboards/edge-sdk 0.2.39 → 0.2.41

package/dist/sensingCatchRate.d.ts

@@ -0,0 +1,246 @@
+/**
+ * The four REPORTING groups. Every table this module produces is grouped by
+ * these and never blended across them, because a promise's group determines
+ * which failure mode can even occur: an Instant promise fails by never being
+ * looked at, a State promise fails by firing on the wrong side of an edge.
+ */
+export type ShapeGroup = 'Instant' | 'Brief' | 'Sustained' | 'State';
+export declare const SHAPE_GROUPS: readonly ShapeGroup[];
+/**
+ * A temporal shape: what the promise is shaped like in TIME, independent of
+ * what it is about. Seven of them cover the live route table.
+ *
+ * `rulePolicy` is the `sensing_routes.re_fire_policy` a route of this shape
+ * carries, and `holdSeconds` is its `sustain_seconds`. Both are named against
+ * the real columns so a shape cannot describe a rule the product cannot
+ * express — the classification is derived from config that exists, not
+ * invented for the eval.
+ */
+export interface TemporalShape {
+    /** Stable id. Used as the key in every report and in the CI baseline. */
+    id: string;
+    /** The reporting group. */
+    group: ShapeGroup;
+    /** Human sentence, in the operator's words. */
+    description: string;
+    /** Inclusive lower bound on event duration, seconds. */
+    minDurationS: number;
+    /** Exclusive upper bound on event duration, seconds. `Infinity` for open. */
+    maxDurationS: number;
+    /** The `sensing_routes.re_fire_policy` this shape is expressed with. */
+    rulePolicy: 'once_per_episode' | 'per_new_entity' | 'on_escalation' | 'nag_until_resolved';
+    /**
+     * Seconds the condition must HOLD before the alert is earned
+     * (`sensing_routes.sustain_seconds`). 0 = fires on the rising edge.
+     */
+    holdSeconds: number;
+    /** A live `sensing_routes.condition_field` of this shape, for grounding. */
+    exampleField: string;
+}
+/**
+ * Seven shapes. Each `exampleField` is a real `condition_field` present in
+ * `sensing_routes` in production — this table is a classification of what we
+ * already sell, not a wish list.
+ *
+ * The duration bands are cut where the FAILURE MODE changes, not on round
+ * numbers. Below ~3 s a 30 s look cadence misses the event outright. Between
+ * 3 s and 30 s the look lands but the single admission slot (7.30 s) may still
+ * lose it. Past 30 s at least one look is guaranteed and the question stops
+ * being "did we see it" and becomes "did we fire on the right edge".
+ */
+export declare const TEMPORAL_SHAPES: readonly TemporalShape[];
+/** Look a shape up by id. `null` — never a throw — for an unknown id. */
+export declare function shapeById(id: string): TemporalShape | null;
+/**
+ * The shape of an annotated event.
+ *
+ * Duration alone does NOT determine the shape: `instant` and `arrival` share a
+ * band and are separated by the rule policy, as do `interaction`/`excursion`
+ * and `condition`/`absence`. So the corpus must carry the policy, and this
+ * function refuses to guess when it is absent rather than silently picking the
+ * first band match — a misclassified event lands in the wrong shape's rate and
+ * is invisible.
+ */
+export declare function classifyShape(durationS: number, rulePolicy: TemporalShape['rulePolicy']): TemporalShape | null;
+/**
+ * P(at least one look lands inside an event of `durationS`) for a periodic
+ * look cadence of `cadenceS` whose phase is uncorrelated with the event.
+ *
+ * `min(d/T, 1)`. An event at least as long as the cadence is caught with
+ * certainty; a shorter one is caught in proportion to how much of the cadence
+ * it occupies. This is the ceiling every other factor multiplies down from.
+ */
+export declare function lookCoverage(durationS: number, cadenceS: number): number;
+/**
+ * The closed-form catch rate over a whole duration sample: `E[min(d/T, 1)]`.
+ *
+ * Note this is driven by the MEAN of the truncated ratio, not by the median
+ * duration. A right-skewed duration sample — which every real activity corpus
+ * is — has a mean well above its median, so quoting `median/T` understates the
+ * rate. That is exactly the arithmetic behind the published baseline: 59,093
+ * activities with a 2.4 s median catch at 18.2%, not at 2.4/30 = 8.0%.
+ */
+export declare function expectedCatchRate(durationsS: readonly number[], cadenceS: number): number | null;
+/** One annotated event: a real interval on a real feed, from the corpus. */
+export interface AnnotatedEvent {
+    /** Unique within a corpus. */
+    id: string;
+    /** Which feed (camera) it happened on. Feeds share ONE admission slot. */
+    feed: string;
+    /** Event class, e.g. `person_opens_facility_door`. */
+    eventClass: string;
+    /** Shape id — must be a `TEMPORAL_SHAPES.id`. */
+    shapeId: string;
+    /** Start, seconds from the start of the replay. */
+    startS: number;
+    /** End, seconds from the start of the replay. Must be > startS. */
+    endS: number;
+    /**
+     * Does this event produce enough pixel change for `MotionGate` to call it?
+     * `false` models the documented still-scene class — a leaking cooler, a
+     * hazard nobody created — which contributes ZERO motion analyses and can
+     * ONLY be found by the periodic heartbeat (connectorCadence.ts header).
+     */
+    producesMotion: boolean;
+}
+export interface SamplerConfig {
+    /**
+     * Look cadence, seconds. The binding constraint. Defaults to the shipped
+     * `LOOK_INTERVAL_MS`.
+     */
+    lookCadenceS: number;
+    /**
+     * Still-scene heartbeat, seconds. The only thing that can find a
+     * `producesMotion: false` event. Defaults to the DOOH periodic default.
+     */
+    heartbeatS: number;
+    /** Concurrent analyses. Local sensing ships exactly ONE. */
+    maxInFlight: number;
+    /** Seconds one analysis occupies the slot. Defaults to the measured 7.30 s. */
+    analyzeS: number;
+    /** Candidate-buffer TTL, seconds. A held frame older than this is dropped. */
+    bufferTtlS: number;
+    /** Max frames the buffer will hold at once, across all feeds. */
+    bufferMaxFrames: number;
+    /**
+     * Probability the model reads a CAUGHT frame correctly, per shape. Supplied
+     * by a scored replay (`scoreFields`), never guessed here. `1` isolates the
+     * temporal layer.
+     */
+    fieldAccuracy: number;
+    /**
+     * Probability an analysis of a frame with NO event in progress nevertheless
+     * satisfies the rule — the content-layer false trigger. Also from a scored
+     * replay.
+     */
+    falsePositiveRate: number;
+}
+export declare const DEFAULT_SAMPLER: Readonly<SamplerConfig>;
+/** Per-event replay outcome. */
+export interface EventOutcome {
+    id: string;
+    shapeId: string;
+    eventClass: string;
+    /** A look landed inside the event. The ceiling. */
+    looked: boolean;
+    /** That look's frame reached the model (directly or via the buffer). */
+    analyzed: boolean;
+    /** The model also read it correctly, so the rule could fire. */
+    caught: boolean;
+    /**
+     * Why it was lost, when it was. These are four DIFFERENT defects with four
+     * different fixes, and collapsing them is how someone ends up buying a
+     * second inference slot to fix a look-cadence problem.
+     *   never_looked  — no look landed inside the event. Fix: look cadence.
+     *   gate_dropped  — a look landed and MotionGate declined to analyse it.
+     *                   Fix: the heartbeat (this is the still-scene case).
+     *   slot_starved  — the gate approved it and the slot was busy. Fix: slots.
+     *   buffer_expired— it was held and the TTL ran out. Fix: TTL or slots.
+     *   model_wrong   — it reached the model and the model read it wrong.
+     */
+    lostTo: 'never_looked' | 'gate_dropped' | 'slot_starved' | 'buffer_expired' | 'model_wrong' | null;
+    /** Seconds from event start to the analysis landing. `null` if never. */
+    latencyS: number | null;
+}
+export interface ReplayResult {
+    outcomes: EventOutcome[];
+    /** Analyses spent on frames with no event in progress. */
+    idleAnalyses: number;
+    /** Idle analyses that nevertheless satisfied a rule — false triggers. */
+    falseTriggers: number;
+    /** Total analyses run. */
+    analyses: number;
+    /** Looks taken. Cheap, but not free — this sizes the CPU claim. */
+    looks: number;
+}
+/**
+ * Replay an annotated corpus through the shipped scheduling law.
+ *
+ * The loop is the real one, in the real order:
+ *   look tick per feed (staggered) -> motion gate -> admission slot ->
+ *   candidate buffer on denial -> pump when the slot frees.
+ *
+ * `durationS` is the replay length; events must fall inside it. `seed` fixes
+ * the per-feed look PHASE, which is the only stochastic input — and it is the
+ * one that matters, because a phase locked to the events would manufacture a
+ * catch rate of either 0% or 100%.
+ */
+export declare function replay(events: readonly AnnotatedEvent[], config: Partial<SamplerConfig> | undefined, { durationS, seed }: {
+    durationS: number;
+    seed?: number;
+}): ReplayResult;
+export interface ShapeReport {
+    shapeId: string;
+    group: ShapeGroup;
+    events: number;
+    /** Fraction of events where a look landed inside. The ceiling. */
+    lookRate: number;
+    /** Fraction of events the model was actually asked about. */
+    analyzeRate: number;
+    /** THE number: fraction of events that produced a correct fire. */
+    catchRate: number;
+    /**
+     * Fires with no event in progress, as a fraction of all fires. Reported
+     * BESIDE the catch rate and never folded into it: a detector that fires
+     * constantly has a perfect catch rate and is worthless.
+     */
+    falseTriggerRate: number;
+    /** Median seconds from event start to the analysis landing, for caught events. */
+    medianLatencyS: number | null;
+    /** Loss attribution — where the missed events went. */
+    lost: {
+        never_looked: number;
+        gate_dropped: number;
+        slot_starved: number;
+        buffer_expired: number;
+        model_wrong: number;
+    };
+}
+/**
+ * Group a replay into one row per shape.
+ *
+ * The false-trigger rate is charged to every shape that was present, because
+ * an idle analysis is not attributable to one shape — it happened when NOTHING
+ * was in progress. Reporting it per shape anyway is deliberate: an operator
+ * reads one row, and a row that hides the noise is the row that sells a
+ * detector nobody can live with.
+ */
+export declare function reportByShape(result: ReplayResult): ShapeReport[];
+/** Roll the shape rows up to the four reporting groups. */
+export declare function reportByGroup(reports: readonly ShapeReport[]): Array<{
+    group: ShapeGroup;
+    events: number;
+    catchRate: number;
+    falseTriggerRate: number;
+    lookRate: number;
+}>;
+/**
+ * The look cadence a shape needs to reach `target`.
+ *
+ * `min(d/T,1) >= target  =>  T <= d/target`. Reported so a red gate carries
+ * the fix rather than only the failure: a 2.2 s event at a 90% target needs a
+ * 2.44 s look cadence, which is a real, affordable number (looking costs
+ * 3.6 ms) and is 12x finer than the 30 s we ship.
+ */
+export declare function requiredLookCadenceS(medianDurationS: number, target: number): number | null;
+//# sourceMappingURL=sensingCatchRate.d.ts.map

package/dist/sensingCatchRate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensingCatchRate.d.ts","sourceRoot":"","sources":["../src/sensingCatchRate.ts"],"names":[],"mappings":"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"}