@orangecharts/wrun-chart-host 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -31,13 +31,17 @@ export interface WrunInputRow {
31
31
  values: number[];
32
32
  cellBlocks?: Map<number, number[]>;
33
33
  }
34
+ /** Replace the registered row-lane tuple widths (web: src/utility/wrun/sources/row-lane-registry.ts, at load and in
35
+ * its spec hook). */
36
+ export declare function registerWrunRowLaneTupleWidths(widths: Readonly<Record<string, number>>): void;
34
37
  /** Cell tuple widths per celled source class (f64 cells per source tuple), the shared host's table
35
38
  * (`WRUN_HOST_CELL_TUPLE_WIDTHS`): `volume_profile` = [low, high, buy, sell]; `book` = [price,
36
39
  * abs(size), side]; `tape` = [offset_ms, price, size, side]; `trade_volume_by_size` = [bucket,
37
40
  * buy_usd, sell_usd, buy_count, sell_count]; `intrabar` and `candles` = [offset_ms, open, high,
38
41
  * low, close, volume]; `options_chain` = [strike, expiry_ms, side, oi, gamma, delta, mark_iv,
39
- * underlying, multiplier, vega]. Read at pack time: a run loaded the host first. `max_cells`
40
- * counts tuples; the packed byte math counts f64s. */
42
+ * underlying, multiplier, vega]; and each registered row lane's own (`registerWrunRowLaneTupleWidths`:
43
+ * the class a host serves through a descriptor, before or after the kit names it). Read at pack
44
+ * time: a run loaded the host first. `max_cells` counts tuples; the packed byte math counts f64s. */
41
45
  export declare function wrunCellTupleWidths(): Readonly<Record<string, number>>;
42
46
  /** The frozen refusal for a block over its input's `max_cells` (the om contract's code, every
43
47
  * host): the evaluation is refused, the block never truncated. An input declaring
@@ -22,15 +22,25 @@ import { abiAtLeast } from '../../interfaces/wrun-runtime.interface.js';
22
22
  import { WRUN_FRAME_DEFAULT_MAX_BYTES, WRUN_FRAME_MAX_SLOTS } from './wrun-frames.js';
23
23
  import { wrunChartHostEnv } from '../../host-env.js';
24
24
  import { wrunPlainText } from './wrun-text-params.util.js';
25
+ /** The tuple widths a host's own row lanes serve (web: each row-lane descriptor's `width`), registered by its
26
+ * registry at load (`registerWrunRowLaneTupleWidths`), so a new lane needs no row in the kit's table. */
27
+ let laneTupleWidths = Object.freeze({});
28
+ /** Replace the registered row-lane tuple widths (web: src/utility/wrun/sources/row-lane-registry.ts, at load and in
29
+ * its spec hook). */
30
+ export function registerWrunRowLaneTupleWidths(widths) {
31
+ laneTupleWidths = Object.freeze({ ...widths });
32
+ }
25
33
  /** Cell tuple widths per celled source class (f64 cells per source tuple), the shared host's table
26
34
  * (`WRUN_HOST_CELL_TUPLE_WIDTHS`): `volume_profile` = [low, high, buy, sell]; `book` = [price,
27
35
  * abs(size), side]; `tape` = [offset_ms, price, size, side]; `trade_volume_by_size` = [bucket,
28
36
  * buy_usd, sell_usd, buy_count, sell_count]; `intrabar` and `candles` = [offset_ms, open, high,
29
37
  * low, close, volume]; `options_chain` = [strike, expiry_ms, side, oi, gamma, delta, mark_iv,
30
- * underlying, multiplier, vega]. Read at pack time: a run loaded the host first. `max_cells`
31
- * counts tuples; the packed byte math counts f64s. */
38
+ * underlying, multiplier, vega]; and each registered row lane's own (`registerWrunRowLaneTupleWidths`:
39
+ * the class a host serves through a descriptor, before or after the kit names it). Read at pack
40
+ * time: a run loaded the host first. `max_cells` counts tuples; the packed byte math counts f64s. */
32
41
  export function wrunCellTupleWidths() {
33
- return wrunChartHostEnv().sharedHost().WRUN_HOST_CELL_TUPLE_WIDTHS;
42
+ const host = wrunChartHostEnv().sharedHost().WRUN_HOST_CELL_TUPLE_WIDTHS;
43
+ return Object.keys(laneTupleWidths).length === 0 ? host : { ...host, ...laneTupleWidths };
34
44
  }
35
45
  /** The frozen refusal for a block over its input's `max_cells` (the om contract's code, every
36
46
  * host): the evaluation is refused, the block never truncated. An input declaring
@@ -34,6 +34,14 @@ export interface WrunHostFillContext {
34
34
  * it from wrunMarketFactsFor now; paramRunValue reads it once the chart's
35
35
  * kit pin (0.65.0) has the `session_open` host_fill word. */
36
36
  sessionOpen?: number;
37
+ /** UW-PARITY S8, the issuer's earnings facts (wrun-earnings-facts.util, the
38
+ * browser run alone): `market.earnings_next_ms()` and
39
+ * `market.earnings_prev_ms()` in epoch ms, `market.earnings_session()` +1
40
+ * before the open, -1 after the close; 0 for each one the chart does not
41
+ * know. */
42
+ earningsNextMs?: number;
43
+ earningsPrevMs?: number;
44
+ earningsSession?: number;
37
45
  }
38
46
  export declare function nonEmptyString(value: unknown): string | undefined;
39
47
  export declare function finiteNumber(value: unknown): number | undefined;
@@ -129,6 +129,14 @@ function paramRunValue(param, flat, host) {
129
129
  return finiteOr(finiteNumber(host?.quoteIsUsd), fallback);
130
130
  if (param.host_fill === 'session_open')
131
131
  return finiteOr(finiteNumber(host?.sessionOpen), fallback);
132
+ // The earnings words (om WRUN_EARNINGS_FACT_FILLS), read before the kit pin names them.
133
+ const fill = param.host_fill;
134
+ if (fill === 'earnings_next_ms')
135
+ return finiteOr(finiteNumber(host?.earningsNextMs), fallback);
136
+ if (fill === 'earnings_prev_ms')
137
+ return finiteOr(finiteNumber(host?.earningsPrevMs), fallback);
138
+ if (fill === 'earnings_session')
139
+ return finiteOr(finiteNumber(host?.earningsSession), fallback);
132
140
  const raw = flat?.[param.name];
133
141
  switch (param.type) {
134
142
  case 'symbol':
@@ -1,3 +1,4 @@
1
+ import { type WrunFailureBaseCause, type WrunFailureCause } from './wrun-failure-cause.js';
1
2
  import { WRUN_KIT_REFUSAL_STAGES, wrunKitRefusalStageOf, type WrunFrameRefusal, type WrunKitRefusalStage } from './wrun-hosted-wire-caps.js';
2
3
  export type WrunRefusalClass = 'legs-empty' | 'feed-missing' | 'no-options' | 'coin-outside-feed' | 'interval-unserved' | 'service-no-answer' | 'waiting' | 'cme-wall' | 'pin-refused' | 'index-unserved' | 'too-big' | 'live-stopped' | 'not-reached' | 'nothing-ready' | 'slots' | 'not-added' | 'run-failed';
3
4
  export type WrunRefusalOut = {
@@ -61,6 +62,20 @@ export interface WrunRefusalTelemetry {
61
62
  /** The server answered a code the answer table has no row for: shown with its code. */
62
63
  unknownCode?: true;
63
64
  }
65
+ /** What a raiser stamps on the error it throws (`stampWrunRefusalTelemetry`): the record's join keys, and the
66
+ * failure's cause when the raiser knows it (`wrunFailureCauseOf` reads it right after a record's own). */
67
+ export interface WrunRefusalStamp extends WrunRefusalTelemetry {
68
+ cause?: WrunFailureCause;
69
+ }
70
+ /**
71
+ * What a record says about its own failure beside the join keys: its cause (`wrunFailureCauseOf`, a word of the
72
+ * closed set in wrun-failure-cause), at the frozen location `refusal.telemetry.cause` the transient grace reads
73
+ * (CLOUD-RUN-ROBUST: a transient cause waits out the grace before it shows). Written only for a cause other than
74
+ * `none`, so a record of a typed verdict serializes as it did before.
75
+ */
76
+ export interface WrunRefusalRecordTelemetry {
77
+ cause: WrunFailureCause;
78
+ }
64
79
  /** The ONE record, serialized in this key order with the params sorted by key. */
65
80
  export interface WrunRefusal extends WrunRefusalTelemetry {
66
81
  v: 1;
@@ -76,6 +91,8 @@ export interface WrunRefusal extends WrunRefusalTelemetry {
76
91
  out: WrunRefusalOut;
77
92
  /** The raiser's technical text: Copy details, and a run-failed record's detail line (its first line). */
78
93
  details: string;
94
+ /** The failure's cause when it is not `none` (`WrunRefusalRecordTelemetry`), written last. */
95
+ telemetry?: WrunRefusalRecordTelemetry;
79
96
  }
80
97
  export type WrunRefusalOverlayTarget = {
81
98
  chartIndex: number;
@@ -146,11 +163,15 @@ export declare const WRUN_REFUSAL_EVENT_MARKET_KEY = "wrun.refusal.market.event"
146
163
  * harvests them. The spec fails when a builtin class or a registered lane has no row here.
147
164
  */
148
165
  export declare const WRUN_REFUSAL_FEED_KEYS: Readonly<Record<string, string>>;
166
+ /** Replace the descriptor-registered feed words (the row-lane registry's, at load and in its spec hook). A
167
+ * word the table above holds keeps the table's key. */
168
+ export declare function registerWrunRefusalFeedKeys(keys: Readonly<Record<string, string>>): void;
149
169
  /** The full literal key of a feed's words, or undefined for a word that names no feed. */
150
170
  export declare function wrunRefusalFeedKey(feed: unknown): string | undefined;
151
171
  /** The variants of a class, in C2 order (the spec walks every one). */
152
172
  export declare function wrunRefusalVariants(cls: WrunRefusalClass): string[];
153
- /** Equal records give equal strings: a fixed key order, the params sorted by key, the telemetry last. */
173
+ /** Equal records give equal strings: a fixed key order, the params sorted by key, the telemetry last (the join
174
+ * keys, then the record's own cause). */
154
175
  export declare function serializeWrunRefusal(r: WrunRefusal): string;
155
176
  /** The record a value holds (its canonical string, or the object itself), or null for anything
156
177
  * that is not a well-formed `v: 1` record. */
@@ -170,10 +191,12 @@ export declare function annotateWrunErrorRefusal<T>(error: T, r: WrunRefusal): T
170
191
  /** The completed record an error carries, or undefined. */
171
192
  export declare function wrunRefusalOf(error: unknown): WrunRefusal | undefined;
172
193
  /** Stamp what the raiser knows of the answer on the error it throws (the cloud lane's transport: the ask's socket
173
- * stamp, the run attempt, a foreign supersede); the record `wrunRefusalFor` completes carries it. Merged over an
174
- * earlier stamp. A non-object throwable is returned as it is. */
175
- export declare function stampWrunRefusalTelemetry<T>(error: T, telemetry: WrunRefusalTelemetry): T;
176
- /** The telemetry a raiser stamped on an error (stampWrunRefusalTelemetry), or none. */
194
+ * stamp, the run attempt, a foreign supersede; a raiser that knows the failure's cause, its word); the record
195
+ * `wrunRefusalFor` completes carries it. Merged over an earlier stamp. A non-object throwable is returned as it is:
196
+ * a raiser wraps one first (`new Error(String(value), { cause: value })`) so the stamp can ride it. */
197
+ export declare function stampWrunRefusalTelemetry<T>(error: T, telemetry: WrunRefusalStamp): T;
198
+ /** The telemetry a raiser stamped on an error (stampWrunRefusalTelemetry): its join keys, or none. The stamped cause
199
+ * is read by `wrunFailureCauseOf` alone. */
177
200
  export declare function wrunRefusalTelemetryOf(error: unknown): WrunRefusalTelemetry;
178
201
  /**
179
202
  * Whether the overlay's source can be opened in the editor (the OUT ladders read it, so Open in
@@ -233,9 +256,34 @@ export declare function wrunRefusalSeedFor(error: unknown, ctx: WrunRefusalConte
233
256
  * an unseeded `WrunSourceDataUnavailableError` -> service-no-answer; else run-failed. A server answer
234
257
  * reads through the one answer table first (wrun-hosted-wire-caps): a superseded create's answer is the
235
258
  * `session-lost` note, one a second ask may pass keeps Retry. The record carries the raiser's telemetry
236
- * (stampWrunRefusalTelemetry) and `unknownCode` for a code the table has no row for.
259
+ * (stampWrunRefusalTelemetry), `unknownCode` for a code the table has no row for, and the failure's cause
260
+ * (`wrunFailureCauseOf`) at `telemetry.cause` when it is not `none`.
237
261
  */
238
262
  export declare function wrunRefusalFor(errorOrSeed: unknown, ctx: WrunRefusalContext): WrunRefusal;
263
+ /**
264
+ * The kScript socket's failure codes and the run capability's denial, by the cause each names: the codes the socket
265
+ * worker leaves a failure with (src/workers/constants/kscript-transport-codes.ts, mirrored here because the package
266
+ * never reads the app's worker constants; tests/utility/wrun/wrun-failure-cause.util.spec.ts holds the mirror to them
267
+ * code for code). A failure carries its code at the head of its message (or on its `code`), never a sentence: only
268
+ * that head is read.
269
+ */
270
+ export declare const WRUN_TRANSPORT_CODE_CAUSES: Readonly<Record<string, WrunFailureBaseCause>>;
271
+ /**
272
+ * Why a failure happened, as one word of the closed set (wrun-failure-cause): what produced it, beside the attempt
273
+ * reason and the refusal class that say what kind of failure it was. Read in this order:
274
+ * 1. the cause of the record annotated on the failure (`refusal.telemetry.cause`; a record without one says `none`),
275
+ * so the three events of one failure (`feature:failed`, `wrun_lane_mount`, `wrun_failure_shown`) name the cause
276
+ * its record names;
277
+ * 2. a cause its raiser stamped (`stampWrunRefusalTelemetry`);
278
+ * 3. its own type, by name (the socket row source's transient reasons, a stopped or unreadable ask, a denied
279
+ * capability, the cloud's whole-run refusal, a dead sandbox, an abort its ask's signal did not cause), the kScript
280
+ * socket's codes (`WRUN_TRANSPORT_CODE_CAUSES`) and our worker's one fixed literal (`backend-unavailable`);
281
+ * 4. the server's answer through the one answer table: `server:<row>`, a superseded create's answer `superseded`;
282
+ * 5. a dropped connection under the run: a lazy chunk (`chunk-load`) or a fetch (`network`);
283
+ * 6. `none` for a typed verdict (`isTypedVerdict`), else `other`.
284
+ * Closed words only, never the message. Never throws.
285
+ */
286
+ export declare function wrunFailureCauseOf(error: unknown): WrunFailureCause;
239
287
  /** The translate a surface injects: vue-i18n's translate with named params and, for a plural key,
240
288
  * the plural choice. */
241
289
  export type WrunRefusalTranslate = (key: string, params?: object, plural?: number) => string;
@@ -29,11 +29,16 @@
29
29
  * - `details` keeps the raiser's technical text for Copy details; a run-failed `generic` or `code`
30
30
  * record also shows its first line under the sentence (`wrunRefusalDetailOf`), since its sentence
31
31
  * cannot name the cause.
32
+ * - What produced the failure is one closed word (`wrunFailureCauseOf`, the set in wrun-failure-cause),
33
+ * which the record carries at `telemetry.cause` when it is not `none`: the transient grace reads it
34
+ * there, and the three failure events (`feature:failed`, `wrun_lane_mount`, `wrun_failure_shown`)
35
+ * name the cause the record names.
32
36
  */
33
37
  import { Intervals } from '../../constants/interval.constants.js';
34
38
  import { isCalendarIntervalLabel } from '../chart/calendar-interval.util.js';
35
- import { WRUN_KIT_REFUSAL_STAGES, WRUN_NO_CANDLES_CODE, wrunFrameRefusalOf, wrunKitRefusalStageOf, wrunServerAnswerOfText, } from './wrun-hosted-wire-caps.js';
36
- import { WrunDeadlineError, WrunNoBarsError, WrunQuarantinedError, WrunSourceDataUnavailableError, WrunWorkerPoisonError, } from './wrun-registry-errors.util.js';
39
+ import { isWrunFailureCause, isWrunTransientFailureCause, wrunServerFailureCause, } from './wrun-failure-cause.js';
40
+ import { WRUN_KIT_REFUSAL_STAGES, WRUN_NO_CANDLES_CODE, wrunFrameRefusalOf, wrunKitRefusalStageOf, wrunServerAnswerOfText, wrunServerAnswerVerdict, } from './wrun-hosted-wire-caps.js';
41
+ import { WrunDeadlineError, WrunIntegrationError, WrunNoBarsError, WrunProvenTwinDeclinedError, WrunQuarantinedError, WrunRegistryAddRefusedError, WrunRegistryHostedOnlyError, WrunSourceDataUnavailableError, WrunWorkerPoisonError, } from './wrun-registry-errors.util.js';
37
42
  /** Every class, in the C2 precedence order (paused before note decides first). */
38
43
  export const WRUN_REFUSAL_CLASSES = Object.freeze([
39
44
  'cme-wall',
@@ -98,16 +103,29 @@ export const WRUN_REFUSAL_FEED_KEYS = Object.freeze({
98
103
  long_short_ratio: 'wrun.refusal.feed.longShortRatio',
99
104
  options_oi: 'wrun.refusal.feed.optionsOi',
100
105
  options_volume: 'wrun.refusal.feed.optionsVolume',
106
+ options_flow: 'wrun.refusal.feed.optionsFlow',
107
+ option_daily: 'wrun.refusal.feed.optionDaily',
108
+ option_stats_10m: 'wrun.refusal.feed.optionStats10m',
101
109
  token_supply: 'wrun.refusal.feed.tokenSupply',
102
110
  treasury_balance: 'wrun.refusal.feed.treasuryBalance',
103
111
  volatility_index: 'wrun.refusal.feed.volatilityIndex',
104
112
  series: 'wrun.refusal.feed.series',
105
113
  });
114
+ /** The feed words a source-lane descriptor names for itself (a row lane's `feedWords`, keyed by its lane key),
115
+ * registered by its registry at load (`registerWrunRefusalFeedKeys`), so a new lane needs no row above. */
116
+ let laneFeedKeys = Object.freeze({});
117
+ /** Replace the descriptor-registered feed words (the row-lane registry's, at load and in its spec hook). A
118
+ * word the table above holds keeps the table's key. */
119
+ export function registerWrunRefusalFeedKeys(keys) {
120
+ laneFeedKeys = Object.freeze({ ...keys });
121
+ }
106
122
  /** The full literal key of a feed's words, or undefined for a word that names no feed. */
107
123
  export function wrunRefusalFeedKey(feed) {
108
- return typeof feed === 'string' && Object.prototype.hasOwnProperty.call(WRUN_REFUSAL_FEED_KEYS, feed)
109
- ? WRUN_REFUSAL_FEED_KEYS[feed]
110
- : undefined;
124
+ if (typeof feed !== 'string')
125
+ return undefined;
126
+ if (Object.prototype.hasOwnProperty.call(WRUN_REFUSAL_FEED_KEYS, feed))
127
+ return WRUN_REFUSAL_FEED_KEYS[feed];
128
+ return Object.prototype.hasOwnProperty.call(laneFeedKeys, feed) ? laneFeedKeys[feed] : undefined;
111
129
  }
112
130
  const row = (sentence, chip, params, extra) => ({ sentence, chip, params, ...extra });
113
131
  /** The C2 table. Keys are full literals (the boot scanner harvests them). */
@@ -130,6 +148,12 @@ const VARIANTS = {
130
148
  'market-note': row('wrun.refusal.sentence.feedMissingNote', 'wrun.refusal.chip.feedMissing', ['feed', 'market'], {
131
149
  severity: 'note',
132
150
  }),
151
+ // A lane reading a backend type the installed protocol package does not name yet (`protocol-pending:<TYPE>`,
152
+ // wrun-protocol-pending.util), refused before any fetch: the app itself lacks the feed, whatever the market.
153
+ 'protocol-pending': row('wrun.refusal.sentence.feedProtocolPending', 'wrun.refusal.chip.feedProtocolPending', ['feed'], { severity: 'paused' }),
154
+ // A series the data plane samples for a configured list of underlyings only, the chart's not among them (a lane's
155
+ // answer refused by name, wrun-lane-refusal.leaf `not-in-10m-universe`): a note when the run draws around it.
156
+ 'not-sampled': row('wrun.refusal.sentence.feedNotSampled', 'wrun.refusal.chip.feedNotSampled', ['feed', 'coin']),
133
157
  },
134
158
  'no-options': {
135
159
  venue: row('wrun.refusal.sentence.noOptionsVenue', 'wrun.refusal.chip.noOptions', ['venue', 'coin'], {
@@ -174,6 +198,9 @@ const VARIANTS = {
174
198
  // The cloud's upstream market-data read failed (the error envelope's DATA_UNAVAILABLE, read off a socket frame by
175
199
  // wrunSocketAskFailure): no feed to name, so the envelope's own words and chip, the ones a protected script shows.
176
200
  'market-data': row('kscript.errors.DATA_UNAVAILABLE', 'kscript.legend.labels.DATA_UNAVAILABLE', []),
201
+ // A read the data source keeps switched off for now (a lane's answer refused by name, wrun-lane-refusal.leaf: the
202
+ // OPTION_PRINT_AGG flow scope reads before their switch turns on); a later Retry may bring it.
203
+ 'switched-off': row('wrun.refusal.sentence.feedSwitchedOff', 'wrun.refusal.chip.feedSwitchedOff', ['feed']),
177
204
  },
178
205
  waiting: {
179
206
  default: row('wrun.refusal.sentence.waiting', 'wrun.refusal.chip.waiting', [], { severity: 'note' }),
@@ -384,9 +411,18 @@ function canonicalTelemetry(value) {
384
411
  ...(value.unknownCode === true ? { unknownCode: true } : {}),
385
412
  };
386
413
  }
387
- /** Equal records give equal strings: a fixed key order, the params sorted by key, the telemetry last. */
414
+ /** A record's own telemetry in canonical form (`WrunRefusalRecordTelemetry`): its cause when it is a word of the
415
+ * closed set other than `none`, else none at all. */
416
+ function canonicalRecordTelemetry(value) {
417
+ if (!isRecordObject(value))
418
+ return undefined;
419
+ return isWrunFailureCause(value.cause) && value.cause !== 'none' ? { cause: value.cause } : undefined;
420
+ }
421
+ /** Equal records give equal strings: a fixed key order, the params sorted by key, the telemetry last (the join
422
+ * keys, then the record's own cause). */
388
423
  export function serializeWrunRefusal(r) {
389
424
  const market = canonicalMarket(r.market);
425
+ const telemetry = canonicalRecordTelemetry(r.telemetry);
390
426
  return JSON.stringify({
391
427
  v: 1,
392
428
  cls: r.cls,
@@ -398,6 +434,7 @@ export function serializeWrunRefusal(r) {
398
434
  out: canonicalOut(r.out) ?? { kind: 'retry' },
399
435
  details: r.details,
400
436
  ...canonicalTelemetry(r),
437
+ ...(telemetry ? { telemetry } : {}),
401
438
  });
402
439
  }
403
440
  /** The record a value holds (its canonical string, or the object itself), or null for anything
@@ -430,6 +467,7 @@ export function parseWrunRefusal(value) {
430
467
  if (!market)
431
468
  return null;
432
469
  }
470
+ const telemetry = canonicalRecordTelemetry(candidate.telemetry);
433
471
  return {
434
472
  v: 1,
435
473
  cls: candidate.cls,
@@ -441,6 +479,7 @@ export function parseWrunRefusal(value) {
441
479
  out,
442
480
  details: candidate.details,
443
481
  ...canonicalTelemetry(candidate),
482
+ ...(telemetry ? { telemetry } : {}),
444
483
  };
445
484
  }
446
485
  /** C2 precedence: paused before note, then the class order, then the canonical string (a total
@@ -496,22 +535,35 @@ export function wrunRefusalOf(error) {
496
535
  }
497
536
  const TELEMETRY_KEY = 'wrunRefusalTelemetry';
498
537
  /** Stamp what the raiser knows of the answer on the error it throws (the cloud lane's transport: the ask's socket
499
- * stamp, the run attempt, a foreign supersede); the record `wrunRefusalFor` completes carries it. Merged over an
500
- * earlier stamp. A non-object throwable is returned as it is. */
538
+ * stamp, the run attempt, a foreign supersede; a raiser that knows the failure's cause, its word); the record
539
+ * `wrunRefusalFor` completes carries it. Merged over an earlier stamp. A non-object throwable is returned as it is:
540
+ * a raiser wraps one first (`new Error(String(value), { cause: value })`) so the stamp can ride it. */
501
541
  export function stampWrunRefusalTelemetry(error, telemetry) {
502
542
  if (!error || typeof error !== 'object')
503
543
  return error;
504
544
  const held = error[TELEMETRY_KEY];
505
- defineHidden(error, TELEMETRY_KEY, canonicalTelemetry({ ...(isRecordObject(held) ? held : {}), ...telemetry }));
545
+ const merged = { ...(isRecordObject(held) ? held : {}), ...telemetry };
546
+ defineHidden(error, TELEMETRY_KEY, {
547
+ ...canonicalTelemetry(merged),
548
+ ...(isWrunFailureCause(merged.cause) ? { cause: merged.cause } : {}),
549
+ });
506
550
  return error;
507
551
  }
508
- /** The telemetry a raiser stamped on an error (stampWrunRefusalTelemetry), or none. */
552
+ /** The telemetry a raiser stamped on an error (stampWrunRefusalTelemetry): its join keys, or none. The stamped cause
553
+ * is read by `wrunFailureCauseOf` alone. */
509
554
  export function wrunRefusalTelemetryOf(error) {
510
555
  if (!error || typeof error !== 'object')
511
556
  return {};
512
557
  const held = error[TELEMETRY_KEY];
513
558
  return isRecordObject(held) ? canonicalTelemetry(held) : {};
514
559
  }
560
+ /** The cause a raiser stamped on an error (stampWrunRefusalTelemetry), or undefined. */
561
+ function stampedFailureCauseOf(error) {
562
+ if (!error || typeof error !== 'object')
563
+ return undefined;
564
+ const held = error[TELEMETRY_KEY];
565
+ return isRecordObject(held) && isWrunFailureCause(held.cause) ? held.cause : undefined;
566
+ }
515
567
  // ---------------------------------------------------------------------------
516
568
  // The editable rule
517
569
  // ---------------------------------------------------------------------------
@@ -916,8 +968,11 @@ const HOST_RULE_RE = /\bWRUN (?:(?:string|frame) slot \d+ write of \d+ bytes|(?:
916
968
  const NETWORK_FAILURE_RE = /\b(?:Failed to fetch|NetworkError|Load failed|network error|dynamically imported module|Importing a module script failed|ChunkLoadError)\b/i;
917
969
  /** The failures a second run can get past: the shared sandbox died under the run (its holder's own
918
970
  * timeout is the run deadline's record) or dropped its live session, a package quarantined on its
919
- * first timeout (the heal waits that one out too), a dropped connection. Every other cause is a
920
- * function of the code, the data and the settings: the planner and the sandbox fail the same way. */
971
+ * first timeout (the heal waits that one out too), a dropped connection, and any failure whose cause
972
+ * is transient (wrun-failure-cause: a socket that dropped, an abort the ask did not cause, our
973
+ * worker's failed request), so a record the transient grace held back shows with Retry. Every other
974
+ * cause is a function of the code, the data and the settings: the planner and the sandbox fail the
975
+ * same way. */
921
976
  function isTransientRunFailure(error, message) {
922
977
  if (error instanceof WrunWorkerPoisonError)
923
978
  return true;
@@ -925,7 +980,7 @@ function isTransientRunFailure(error, message) {
925
980
  return true;
926
981
  if (error instanceof WrunQuarantinedError)
927
982
  return error.reason === 'timeout' && error.strikes === 1;
928
- return NETWORK_FAILURE_RE.test(message);
983
+ return NETWORK_FAILURE_RE.test(message) || isWrunTransientFailureCause(unrecordedFailureCauseOf(error));
929
984
  }
930
985
  /** The first non-empty line of a text, trimmed with its runs of spaces collapsed. */
931
986
  function firstLineOf(text) {
@@ -957,6 +1012,9 @@ function variantFor(seed, ctx) {
957
1012
  return declared;
958
1013
  if (declared === 'market-paused' || declared === 'market-note')
959
1014
  return declared;
1015
+ // The app's own lack of the feed, or the data plane's list of sampled underlyings: no market fact moves either.
1016
+ if (declared === 'protocol-pending' || declared === 'not-sampled')
1017
+ return declared;
960
1018
  if (declared === undefined && !cryptoChart)
961
1019
  return 'crypto-only';
962
1020
  return seed.severity === 'note' ? 'market-note' : 'market-paused';
@@ -1113,7 +1171,7 @@ function defaultSeverity(cls) {
1113
1171
  ? 'note'
1114
1172
  : 'paused';
1115
1173
  }
1116
- function buildRecord(seed, ctx, details, telemetry = {}) {
1174
+ function buildRecord(seed, ctx, details, telemetry = {}, cause = 'none') {
1117
1175
  const cls = seed.cls;
1118
1176
  const variant = variantFor(seed, ctx);
1119
1177
  const spec = variantSpec(cls, variant) ?? RUN_FAILED_GENERIC;
@@ -1132,6 +1190,8 @@ function buildRecord(seed, ctx, details, telemetry = {}) {
1132
1190
  out,
1133
1191
  details,
1134
1192
  ...telemetry,
1193
+ // A typed verdict's record carries no cause: it serializes as it did before the cause existed.
1194
+ ...(cause !== 'none' ? { telemetry: { cause } } : {}),
1135
1195
  };
1136
1196
  // A feed with no words cannot be named: the generic words, the class's way out kept.
1137
1197
  if (spec.params.includes('feed') && wrunRefusalFeedKey(params.feed) === undefined) {
@@ -1159,7 +1219,8 @@ export function wrunRefusalSeedFor(error, ctx) {
1159
1219
  * an unseeded `WrunSourceDataUnavailableError` -> service-no-answer; else run-failed. A server answer
1160
1220
  * reads through the one answer table first (wrun-hosted-wire-caps): a superseded create's answer is the
1161
1221
  * `session-lost` note, one a second ask may pass keeps Retry. The record carries the raiser's telemetry
1162
- * (stampWrunRefusalTelemetry) and `unknownCode` for a code the table has no row for.
1222
+ * (stampWrunRefusalTelemetry), `unknownCode` for a code the table has no row for, and the failure's cause
1223
+ * (`wrunFailureCauseOf`) at `telemetry.cause` when it is not `none`.
1163
1224
  */
1164
1225
  export function wrunRefusalFor(errorOrSeed, ctx) {
1165
1226
  let details = '';
@@ -1171,7 +1232,7 @@ export function wrunRefusalFor(errorOrSeed, ctx) {
1171
1232
  const telemetry = wrunRefusalTelemetryOf(errorOrSeed);
1172
1233
  if (wrunServerAnswerOfText(details)?.unknownCode === true)
1173
1234
  telemetry.unknownCode = true;
1174
- return buildRecord(seedOfError(errorOrSeed, ctx), ctx, details, telemetry);
1235
+ return buildRecord(seedOfError(errorOrSeed, ctx), ctx, details, telemetry, unrecordedFailureCauseOf(errorOrSeed));
1175
1236
  }
1176
1237
  catch {
1177
1238
  return {
@@ -1186,6 +1247,174 @@ export function wrunRefusalFor(errorOrSeed, ctx) {
1186
1247
  };
1187
1248
  }
1188
1249
  }
1250
+ // ---------------------------------------------------------------------------
1251
+ // The failure cause (CLOUD-RUN-ROBUST C1, wrun-failure-cause)
1252
+ // ---------------------------------------------------------------------------
1253
+ /**
1254
+ * The kScript socket's failure codes and the run capability's denial, by the cause each names: the codes the socket
1255
+ * worker leaves a failure with (src/workers/constants/kscript-transport-codes.ts, mirrored here because the package
1256
+ * never reads the app's worker constants; tests/utility/wrun/wrun-failure-cause.util.spec.ts holds the mirror to them
1257
+ * code for code). A failure carries its code at the head of its message (or on its `code`), never a sentence: only
1258
+ * that head is read.
1259
+ */
1260
+ export const WRUN_TRANSPORT_CODE_CAUSES = Object.freeze({
1261
+ KSCRIPT_TRANSPORT_DISCONNECTED: 'connection-lost',
1262
+ KSCRIPT_TRANSPORT_DIAL_FAILED: 'dial-failed',
1263
+ KSCRIPT_TRANSPORT_STALE: 'socket-stale',
1264
+ KSCRIPT_WORKER_RESTARTED: 'worker-restarted',
1265
+ KSCRIPT_CAPABILITY_UNAVAILABLE: 'capability-unavailable',
1266
+ KSCRIPT_CAPABILITY_DENIED: 'access-denied',
1267
+ });
1268
+ /** The code a failure's message leads with: an upper-case word the rest does not continue. */
1269
+ const LEADING_FAILURE_CODE = /^([A-Z][A-Z0-9_]*)(?![A-Za-z0-9_])/;
1270
+ /** The protected worker control's words for a failure that carried none (kscript-protected.worker): a fixed literal
1271
+ * of our own worker, read whole, never a pattern. The kScript backend did not process the ask. */
1272
+ const KSCRIPT_REQUEST_FAILED = 'Failed to process KScript request';
1273
+ /** The module words of NETWORK_FAILURE_RE: a lazily loaded chunk that did not arrive. */
1274
+ const CHUNK_LOAD_FAILURE_RE = /\b(?:dynamically imported module|Importing a module script failed|ChunkLoadError)\b/i;
1275
+ /** The lane's typed errors whose own type says what failed (a refusal of a gate, the market or the data, the run
1276
+ * deadline, the adapter, a quarantined or hosted-only package, a declined twin): their cause is `none`. */
1277
+ const TYPED_VERDICT_ERRORS = [
1278
+ WrunRegistryAddRefusedError,
1279
+ WrunNoBarsError,
1280
+ WrunDeadlineError,
1281
+ WrunIntegrationError,
1282
+ WrunQuarantinedError,
1283
+ WrunRegistryHostedOnlyError,
1284
+ WrunProvenTwinDeclinedError,
1285
+ ];
1286
+ /** The context the stable codes read with no chart in hand (the cause reads only whether a code names a refusal). */
1287
+ const NO_CONTEXT = { indicatorName: '', editable: false, hasSettings: false };
1288
+ function errorNameOf(error) {
1289
+ return isRecordObject(error) && typeof error.name === 'string' ? error.name : undefined;
1290
+ }
1291
+ /** The cause of a server answer: a superseded create's answer is `superseded`, any other the row that read it. */
1292
+ function serverAnswerCauseOf(answer) {
1293
+ if (answer === undefined)
1294
+ return undefined;
1295
+ return answer.verdict === 'stale' ? 'superseded' : wrunServerFailureCause(answer.row);
1296
+ }
1297
+ /** The cause of the socket row source's whole-run refusal (its `WrunSocketRefusalError`, read by name): a reply the
1298
+ * chart cannot read, another chart's or tab's supersede, else the server's answer by its frame (the refusal's
1299
+ * message), else by its code through the same table. */
1300
+ function socketRefusalCauseOf(error) {
1301
+ const refusal = socketRefusalOf(error);
1302
+ if (refusal === undefined)
1303
+ return 'other';
1304
+ if (refusal.code === WRUN_LEGACY_RESULT_CODE)
1305
+ return 'reply-unreadable';
1306
+ if (refusal.code === WRUN_SESSION_LOST_CODE)
1307
+ return 'superseded';
1308
+ return (serverAnswerCauseOf(wrunServerAnswerOfText(messageOf(error)) ??
1309
+ wrunServerAnswerVerdict({ details: { wrunRefusal: refusal } }) ??
1310
+ wrunServerAnswerVerdict({ code: refusal.code })) ?? wrunServerFailureCause('unknown-code'));
1311
+ }
1312
+ /** The cause a failure's own type names, read by its name (the socket row source's errors stay out of this module's
1313
+ * graph, and a module duplicate under test still matches), else undefined. */
1314
+ function namedFailureCauseOf(error) {
1315
+ switch (errorNameOf(error)) {
1316
+ case 'WrunRowSourceTransientError': {
1317
+ // The socket row source's transient reasons are causes of the closed set, word for word.
1318
+ const reason = error.reason;
1319
+ return isWrunFailureCause(reason) ? reason : undefined;
1320
+ }
1321
+ case 'WrunSocketRowSourceStopped':
1322
+ return 'superseded';
1323
+ case 'WrunChartGoneError':
1324
+ // A run the overlay's own newer intent superseded is rewrapped as the quiet chart-gone stop with that cause.
1325
+ return error.cause === 'superseded' ? 'superseded' : 'chart-gone';
1326
+ case 'WrunSocketAccessDeniedError':
1327
+ return 'access-denied';
1328
+ case 'SessionExpiredError':
1329
+ // The login lapsed before the run could take its permission: terminal until the person signs in again.
1330
+ return 'session-expired';
1331
+ case 'WrunSocketReplyUnreadable':
1332
+ return 'reply-unreadable';
1333
+ case 'WrunSocketRefusalError':
1334
+ return socketRefusalCauseOf(error);
1335
+ case 'WrunWorkerPoisonError':
1336
+ case 'WrunLiveSessionLostError':
1337
+ return 'worker-dead';
1338
+ case 'AbortError':
1339
+ // An abort that reached a failure: one the ask's own signal did not cause (its own stop never fails a run).
1340
+ return 'aborted';
1341
+ default:
1342
+ return undefined;
1343
+ }
1344
+ }
1345
+ /** The cause a kScript socket code names: the failure's `code`, else the code its message leads with. */
1346
+ function transportCodeCauseOf(error, message) {
1347
+ const carried = isRecordObject(error) ? error.code : undefined;
1348
+ const code = typeof carried === 'string' && Object.hasOwn(WRUN_TRANSPORT_CODE_CAUSES, carried)
1349
+ ? carried
1350
+ : LEADING_FAILURE_CODE.exec(message)?.[1];
1351
+ return code !== undefined && Object.hasOwn(WRUN_TRANSPORT_CODE_CAUSES, code)
1352
+ ? WRUN_TRANSPORT_CODE_CAUSES[code]
1353
+ : undefined;
1354
+ }
1355
+ /** A failure that already says what it is: a typed error of the lane, a refusal seed its raiser attached, a bare seed,
1356
+ * a stable code of the browser lane, the Indicator's own code stopping (the engine's trap, the host's rules). */
1357
+ function isTypedVerdict(error, message) {
1358
+ if (TYPED_VERDICT_ERRORS.some((type) => error instanceof type))
1359
+ return true;
1360
+ if (wrunRefusalSeedOf(error) !== undefined)
1361
+ return true;
1362
+ if (!(error instanceof Error) && validSeed(error) !== undefined)
1363
+ return true;
1364
+ if (seedFromCodes(message, NO_CONTEXT) !== undefined)
1365
+ return true;
1366
+ return ENGINE_TRAP_RE.test(firstLineOf(message)) || HOST_RULE_RE.test(message);
1367
+ }
1368
+ /**
1369
+ * Why a failure happened, as one word of the closed set (wrun-failure-cause): what produced it, beside the attempt
1370
+ * reason and the refusal class that say what kind of failure it was. Read in this order:
1371
+ * 1. the cause of the record annotated on the failure (`refusal.telemetry.cause`; a record without one says `none`),
1372
+ * so the three events of one failure (`feature:failed`, `wrun_lane_mount`, `wrun_failure_shown`) name the cause
1373
+ * its record names;
1374
+ * 2. a cause its raiser stamped (`stampWrunRefusalTelemetry`);
1375
+ * 3. its own type, by name (the socket row source's transient reasons, a stopped or unreadable ask, a denied
1376
+ * capability, the cloud's whole-run refusal, a dead sandbox, an abort its ask's signal did not cause), the kScript
1377
+ * socket's codes (`WRUN_TRANSPORT_CODE_CAUSES`) and our worker's one fixed literal (`backend-unavailable`);
1378
+ * 4. the server's answer through the one answer table: `server:<row>`, a superseded create's answer `superseded`;
1379
+ * 5. a dropped connection under the run: a lazy chunk (`chunk-load`) or a fetch (`network`);
1380
+ * 6. `none` for a typed verdict (`isTypedVerdict`), else `other`.
1381
+ * Closed words only, never the message. Never throws.
1382
+ */
1383
+ export function wrunFailureCauseOf(error) {
1384
+ try {
1385
+ const record = wrunRefusalOf(error);
1386
+ if (record !== undefined)
1387
+ return record.telemetry?.cause ?? 'none';
1388
+ }
1389
+ catch {
1390
+ return 'other';
1391
+ }
1392
+ return unrecordedFailureCauseOf(error);
1393
+ }
1394
+ /** Steps 2 to 6 of `wrunFailureCauseOf`: the cause of a failure no record decided yet (`wrunRefusalFor` writes it
1395
+ * into the record it completes). Never throws. */
1396
+ function unrecordedFailureCauseOf(error) {
1397
+ try {
1398
+ const stamped = stampedFailureCauseOf(error);
1399
+ if (stamped !== undefined)
1400
+ return stamped;
1401
+ const message = messageOf(error);
1402
+ const named = namedFailureCauseOf(error) ?? transportCodeCauseOf(error, message);
1403
+ if (named !== undefined)
1404
+ return named;
1405
+ if (message === KSCRIPT_REQUEST_FAILED)
1406
+ return 'backend-unavailable';
1407
+ const answered = serverAnswerCauseOf(wrunServerAnswerOfText(message));
1408
+ if (answered !== undefined)
1409
+ return answered;
1410
+ if (NETWORK_FAILURE_RE.test(message))
1411
+ return CHUNK_LOAD_FAILURE_RE.test(message) ? 'chunk-load' : 'network';
1412
+ return isTypedVerdict(error, message) ? 'none' : 'other';
1413
+ }
1414
+ catch {
1415
+ return 'other';
1416
+ }
1417
+ }
1189
1418
  function outLabelOf(out, t) {
1190
1419
  switch (out.kind) {
1191
1420
  case 'switch-market':
@@ -775,6 +775,7 @@ memo) {
775
775
  ? {
776
776
  title: wrunFrameTitle(frame) ?? declaredTitle(drawing.title) ?? drawing.name,
777
777
  lines: frame.lines,
778
+ ...(frame.markets !== undefined ? { markets: frame.markets } : {}),
778
779
  ...(anchor !== undefined ? { anchor } : {}),
779
780
  ...(offset !== undefined ? { offset: [...offset] } : {}),
780
781
  ...(z !== undefined ? { z } : {}),
@@ -0,0 +1,29 @@
1
+ /** The longest option root a contract names (the OSI root field). */
2
+ export declare const WRUN_ROW_MARKET_ROOT_MAX_CHARS = 6;
3
+ /** A contract's strike stays below this (eight digits of thousandths). */
4
+ export declare const WRUN_ROW_MARKET_STRIKE_LIMIT = 100000;
5
+ export declare const WRUN_ROW_MARKET_MESSAGE = "a market is null, { \"contract\": [root_code, expiry_ms, side_cp, strike] } or { \"ticker\": code }";
6
+ export declare const WRUN_ROW_MARKET_CONTRACT_MESSAGE = "a contract is [root_code, expiry_ms, side_cp, strike]: the option root's symbol code (1 to 6 characters), the expiry in epoch milliseconds, +1 for a call or -1 for a put, and a strike above 0 and below 100000";
7
+ export declare const WRUN_ROW_MARKET_TICKER_MESSAGE = "a ticker is a symbol code of 1 to 10 characters";
8
+ /** The two market forms a row or a line names. */
9
+ export type WrunRowMarket = {
10
+ contract: [rootCode: number, expiryMs: number, sideCp: number, strike: number];
11
+ } | {
12
+ ticker: number;
13
+ };
14
+ /** One non-null entry's refusal (its path below the entry and the kit's words), or null when it
15
+ * names a market. */
16
+ export declare function wrunRowMarketIssue(value: unknown): {
17
+ path: string[];
18
+ message: string;
19
+ } | null;
20
+ /** The refusal when `markets` and the rows it names differ in length (the kit's words). */
21
+ export declare function wrunRowMarketsLengthMessage(noun: 'row' | 'line', count: number): string;
22
+ /** A frame's `markets`, checked against its row or line count: the list as written (each entry a
23
+ * copy), or the refusal as `[path, message]` (the path below the frame). */
24
+ export declare function parseWrunRowMarkets(value: unknown, noun: 'row' | 'line', count: number): {
25
+ markets: (WrunRowMarket | null)[];
26
+ } | {
27
+ path: (string | number)[];
28
+ message: string;
29
+ };