footprintjs 10.0.1 → 10.2.0

package/dist/esm/lib/attempt/category.js

@@ -0,0 +1,131 @@
+/**
+ * attempt/category.ts — `errorCategory`, the ONE failure classifier (design §3.9).
+ *
+ * Seven fixed values, so every recorder — the narrative, the metric layer, an agent's own — breaks failures down
+ * the same way; a recorder never invents a category of its own. Borrowed from agentfootprint's
+ * `classifyRetryReason` and widened, so its decorators adopt this one rather than keep theirs.
+ *
+ * Category is EVIDENCE, never policy: the default `retryOn` retries every category. A chart that wants "never
+ * retry a permanent failure" says so: `retryOn: (e) => errorCategory(e) !== 'permanent'`.
+ *
+ * Precedence — what the failure LOOKED like wins over what it declares:
+ *   1. the attempt's own timer (outcome `'timeout'`, or our `AttemptTimeoutError`)  → timeout
+ *   2. the run's signal ended it (outcome `'aborted'`)                              → unknown
+ *   3. status 429, or a declared `retryAfterMs` / `retryAfterSeconds`               → rate-limited
+ *   4. status 5xx                                                                   → server
+ *   5. status 401 / 403                                                             → auth
+ *   6. any other 4xx                                                                → permanent
+ *   7. `retryable: false`, or a validation error                                    → permanent
+ *   8. a transport failure (a socket code on the error or its cause, a fetch
+ *      `TypeError`, an `AbortError` / `TimeoutError` that was not the run's)        → network
+ *   9. anything else                                                                → unknown
+ *
+ * A status is a NUMBER (`status` or `statusCode`); a numeric string is not read as one. Total: a value whose
+ * reads throw (a hostile Proxy) is `'unknown'`, never a second throw from an error path.
+ */
+import { InputValidationError } from '../schema/errors.js';
+import { AttemptTimeoutError, UnknownEffectError } from './errors.js';
+/** Socket-level codes a transport failure carries (Node's `errno` names). */
+const NETWORK_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'EPIPE',
+]);
+/** The messages runtimes give a `fetch` that never reached the server (Node, Chromium, Firefox, Safari). */
+const FETCH_FAILURE = /^(fetch failed|failed to fetch|networkerror when attempting to fetch resource\.?|load failed)$/i;
+/** Error names that say a validation failed — retrying the same input cannot succeed. */
+const VALIDATION_NAMES = new Set(['ValidationError', 'ZodError', 'InputValidationError']);
+/** Error names of an abort or a timeout that some OTHER signal raised (the run's own ends as outcome `'aborted'`). */
+const TRANSPORT_ABORT_NAMES = new Set(['AbortError', 'TimeoutError']);
+/**
+ * The category of an attempt's failure. `outcome` is how the attempt ended (default `'failed'`): it decides
+ * `'timeout'` (the attempt's own timer) and `'unknown'` (the run's signal) before the error is read.
+ */
+export function errorCategory(error, outcome = 'failed') {
+    if (outcome === 'timeout')
+        return 'timeout';
+    if (outcome === 'aborted')
+        return 'unknown';
+    try {
+        return categoryOf(error);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * @internal Terminal ownership preserves a producer's known category. An
+ * unresolved effect is unknown, never the category of its physical cause.
+ * This does not rewrite historical attempt categories or re-read a known one.
+ */
+export function terminalCategory(error, known) {
+    try {
+        if (error instanceof UnknownEffectError)
+            return 'unknown';
+        // CJS and ESM have distinct constructors. A declared own DATA name may
+        // only reduce certainty to unknown; never execute an error's name getter
+        // or promote its physical cause to a known outcome across module copies.
+        if (error !== null && (typeof error === 'object' || typeof error === 'function')) {
+            const name = Object.getOwnPropertyDescriptor(error, 'name');
+            if (name && Object.prototype.hasOwnProperty.call(name, 'value') && name.value === 'UnknownEffectError') {
+                return 'unknown';
+            }
+        }
+    }
+    catch {
+        return known ?? 'unknown';
+    }
+    return known ?? errorCategory(error);
+}
+function categoryOf(error) {
+    if (error instanceof AttemptTimeoutError)
+        return 'timeout';
+    if (error === null || (typeof error !== 'object' && typeof error !== 'function'))
+        return 'unknown';
+    const fields = error;
+    const status = numberField(fields, 'status') ?? numberField(fields, 'statusCode');
+    const declaresRetryAfter = isWait(fields.retryAfterMs) || isWait(fields.retryAfterSeconds);
+    if (status === 429 || declaresRetryAfter)
+        return 'rate-limited';
+    if (status !== undefined && status >= 500 && status <= 599)
+        return 'server';
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status !== undefined && status >= 400 && status <= 499)
+        return 'permanent';
+    if (fields.retryable === false)
+        return 'permanent';
+    if (error instanceof InputValidationError)
+        return 'permanent';
+    const name = typeof fields.name === 'string' ? fields.name : undefined;
+    if (name !== undefined && VALIDATION_NAMES.has(name))
+        return 'permanent';
+    if (status === undefined && isTransportFailure(fields, name))
+        return 'network';
+    return 'unknown';
+}
+function isTransportFailure(fields, name) {
+    if (hasNetworkCode(fields.code))
+        return true;
+    const cause = fields.cause;
+    if (cause !== null && typeof cause === 'object' && hasNetworkCode(cause.code)) {
+        return true;
+    }
+    if (name !== undefined && TRANSPORT_ABORT_NAMES.has(name))
+        return true;
+    return fields instanceof TypeError && typeof fields.message === 'string' && FETCH_FAILURE.test(fields.message);
+}
+function hasNetworkCode(code) {
+    return typeof code === 'string' && NETWORK_CODES.has(code);
+}
+function numberField(fields, key) {
+    const value = fields[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function isWait(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2F0ZWdvcnkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvbGliL2F0dGVtcHQvY2F0ZWdvcnkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXdCRztBQUVILE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQzNELE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUd0RSw2RUFBNkU7QUFDN0UsTUFBTSxhQUFhLEdBQXdCLElBQUksR0FBRyxDQUFDO0lBQ2pELFlBQVk7SUFDWixjQUFjO0lBQ2QsV0FBVztJQUNYLFdBQVc7SUFDWCxXQUFXO0lBQ1gsT0FBTztDQUNSLENBQUMsQ0FBQztBQUVILDRHQUE0RztBQUM1RyxNQUFNLGFBQWEsR0FBRyxpR0FBaUcsQ0FBQztBQUV4SCx5RkFBeUY7QUFDekYsTUFBTSxnQkFBZ0IsR0FBd0IsSUFBSSxHQUFHLENBQUMsQ0FBQyxpQkFBaUIsRUFBRSxVQUFVLEVBQUUsc0JBQXNCLENBQUMsQ0FBQyxDQUFDO0FBRS9HLHNIQUFzSDtBQUN0SCxNQUFNLHFCQUFxQixHQUF3QixJQUFJLEdBQUcsQ0FBQyxDQUFDLFlBQVksRUFBRSxjQUFjLENBQUMsQ0FBQyxDQUFDO0FBRTNGOzs7R0FHRztBQUNILE1BQU0sVUFBVSxhQUFhLENBQUMsS0FBYyxFQUFFLFVBQTBCLFFBQVE7SUFDOUUsSUFBSSxPQUFPLEtBQUssU0FBUztRQUFFLE9BQU8sU0FBUyxDQUFDO0lBQzVDLElBQUksT0FBTyxLQUFLLFNBQVM7UUFBRSxPQUFPLFNBQVMsQ0FBQztJQUM1QyxJQUFJLENBQUM7UUFDSCxPQUFPLFVBQVUsQ0FBQyxLQUFLLENBQUMsQ0FBQztJQUMzQixDQUFDO0lBQUMsTUFBTSxDQUFDO1FBQ1AsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztBQUNILENBQUM7QUFFRDs7OztHQUlH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QUM3QyxNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDO0lBQzNCLElBQUksS0FBSyxLQUFLLElBQUksSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksY0FBYyxDQUFFLEtBQWlDLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQztRQUMzRyxPQUFPLElBQUksQ0FBQztJQUNkLENBQUM7SUFDRCxJQUFJLElBQUksS0FBSyxTQUFTLElBQUkscUJBQXFCLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQztRQUFFLE9BQU8sSUFBSSxDQUFDO0lBQ3ZFLE9BQU8sTUFBTSxZQUFZLFNBQVMsSUFBSSxPQUFPLE1BQU0sQ0FBQyxPQUFPLEtBQUssUUFBUSxJQUFJLGFBQWEsQ0FBQyxJQUFJLENBQUMsTUFBTSxDQUFDLE9BQU8sQ0FBQyxDQUFDO0FBQ2pILENBQUM7QUFFRCxTQUFTLGNBQWMsQ0FBQyxJQUFhO0lBQ25DLE9BQU8sT0FBTyxJQUFJLEtBQUssUUFBUSxJQUFJLGFBQWEsQ0FBQyxHQUFHLENBQUMsSUFBSSxDQUFDLENBQUM7QUFDN0QsQ0FBQztBQUVELFNBQVMsV0FBVyxDQUFDLE1BQStCLEVBQUUsR0FBNEI7SUFDaEYsTUFBTSxLQUFLLEdBQUcsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQzFCLE9BQU8sT0FBTyxLQUFLLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO0FBQ2pGLENBQUM7QUFFRCxTQUFTLE1BQU0sQ0FBQyxLQUFjO0lBQzVCLE9BQU8sT0FBTyxLQUFLLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxJQUFJLENBQUMsQ0FBQztBQUMzRSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBhdHRlbXB0L2NhdGVnb3J5LnRzIOKAlCBgZXJyb3JDYXRlZ29yeWAsIHRoZSBPTkUgZmFpbHVyZSBjbGFzc2lmaWVyIChkZXNpZ24gwqczLjkpLlxuICpcbiAqIFNldmVuIGZpeGVkIHZhbHVlcywgc28gZXZlcnkgcmVjb3JkZXIg4oCUIHRoZSBuYXJyYXRpdmUsIHRoZSBtZXRyaWMgbGF5ZXIsIGFuIGFnZW50J3Mgb3duIOKAlCBicmVha3MgZmFpbHVyZXMgZG93blxuICogdGhlIHNhbWUgd2F5OyBhIHJlY29yZGVyIG5ldmVyIGludmVudHMgYSBjYXRlZ29yeSBvZiBpdHMgb3duLiBCb3Jyb3dlZCBmcm9tIGFnZW50Zm9vdHByaW50J3NcbiAqIGBjbGFzc2lmeVJldHJ5UmVhc29uYCBhbmQgd2lkZW5lZCwgc28gaXRzIGRlY29yYXRvcnMgYWRvcHQgdGhpcyBvbmUgcmF0aGVyIHRoYW4ga2VlcCB0aGVpcnMuXG4gKlxuICogQ2F0ZWdvcnkgaXMgRVZJREVOQ0UsIG5ldmVyIHBvbGljeTogdGhlIGRlZmF1bHQgYHJldHJ5T25gIHJldHJpZXMgZXZlcnkgY2F0ZWdvcnkuIEEgY2hhcnQgdGhhdCB3YW50cyBcIm5ldmVyXG4gKiByZXRyeSBhIHBlcm1hbmVudCBmYWlsdXJlXCIgc2F5cyBzbzogYHJldHJ5T246IChlKSA9PiBlcnJvckNhdGVnb3J5KGUpICE9PSAncGVybWFuZW50J2AuXG4gKlxuICogUHJlY2VkZW5jZSDigJQgd2hhdCB0aGUgZmFpbHVyZSBMT09LRUQgbGlrZSB3aW5zIG92ZXIgd2hhdCBpdCBkZWNsYXJlczpcbiAqICAgMS4gdGhlIGF0dGVtcHQncyBvd24gdGltZXIgKG91dGNvbWUgYCd0aW1lb3V0J2AsIG9yIG91ciBgQXR0ZW1wdFRpbWVvdXRFcnJvcmApICDihpIgdGltZW91dFxuICogICAyLiB0aGUgcnVuJ3Mgc2lnbmFsIGVuZGVkIGl0IChvdXRjb21lIGAnYWJvcnRlZCdgKSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIOKGkiB1bmtub3duXG4gKiAgIDMuIHN0YXR1cyA0MjksIG9yIGEgZGVjbGFyZWQgYHJldHJ5QWZ0ZXJNc2AgLyBgcmV0cnlBZnRlclNlY29uZHNgICAgICAgICAgICAgICAg4oaSIHJhdGUtbGltaXRlZFxuICogICA0LiBzdGF0dXMgNXh4ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIOKGkiBzZXJ2ZXJcbiAqICAgNS4gc3RhdHVzIDQwMSAvIDQwMyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICDihpIgYXV0aFxuICogICA2LiBhbnkgb3RoZXIgNHh4ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIOKGkiBwZXJtYW5lbnRcbiAqICAgNy4gYHJldHJ5YWJsZTogZmFsc2VgLCBvciBhIHZhbGlkYXRpb24gZXJyb3IgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICDihpIgcGVybWFuZW50XG4gKiAgIDguIGEgdHJhbnNwb3J0IGZhaWx1cmUgKGEgc29ja2V0IGNvZGUgb24gdGhlIGVycm9yIG9yIGl0cyBjYXVzZSwgYSBmZXRjaFxuICogICAgICBgVHlwZUVycm9yYCwgYW4gYEFib3J0RXJyb3JgIC8gYFRpbWVvdXRFcnJvcmAgdGhhdCB3YXMgbm90IHRoZSBydW4ncykgICAgICAgIOKGkiBuZXR3b3JrXG4gKiAgIDkuIGFueXRoaW5nIGVsc2UgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg4oaSIHVua25vd25cbiAqXG4gKiBBIHN0YXR1cyBpcyBhIE5VTUJFUiAoYHN0YXR1c2Agb3IgYHN0YXR1c0NvZGVgKTsgYSBudW1lcmljIHN0cmluZyBpcyBub3QgcmVhZCBhcyBvbmUuIFRvdGFsOiBhIHZhbHVlIHdob3NlXG4gKiByZWFkcyB0aHJvdyAoYSBob3N0aWxlIFByb3h5KSBpcyBgJ3Vua25vd24nYCwgbmV2ZXIgYSBzZWNvbmQgdGhyb3cgZnJvbSBhbiBlcnJvciBwYXRoLlxuICovXG5cbmltcG9ydCB7IElucHV0VmFsaWRhdGlvbkVycm9yIH0gZnJvbSAnLi4vc2NoZW1hL2Vycm9ycy5qcyc7XG5pbXBvcnQgeyBBdHRlbXB0VGltZW91dEVycm9yLCBVbmtub3duRWZmZWN0RXJyb3IgfSBmcm9tICcuL2Vycm9ycy5qcyc7XG5pbXBvcnQgdHlwZSB7IEF0dGVtcHRDYXRlZ29yeSwgQXR0ZW1wdE91dGNvbWUgfSBmcm9tICcuL3R5cGVzLmpzJztcblxuLyoqIFNvY2tldC1sZXZlbCBjb2RlcyBhIHRyYW5zcG9ydCBmYWlsdXJlIGNhcnJpZXMgKE5vZGUncyBgZXJybm9gIG5hbWVzKS4gKi9cbmNvbnN0IE5FVFdPUktfQ09ERVM6IFJlYWRvbmx5U2V0PHN0cmluZz4gPSBuZXcgU2V0KFtcbiAgJ0VDT05OUkVTRVQnLFxuICAnRUNPTk5SRUZVU0VEJyxcbiAgJ0VOT1RGT1VORCcsXG4gICdFVElNRURPVVQnLFxuICAnRUFJX0FHQUlOJyxcbiAgJ0VQSVBFJyxcbl0pO1xuXG4vKiogVGhlIG1lc3NhZ2VzIHJ1bnRpbWVzIGdpdmUgYSBgZmV0Y2hgIHRoYXQgbmV2ZXIgcmVhY2hlZCB0aGUgc2VydmVyIChOb2RlLCBDaHJvbWl1bSwgRmlyZWZveCwgU2FmYXJpKS4gKi9cbmNvbnN0IEZFVENIX0ZBSUxVUkUgPSAvXihmZXRjaCBmYWlsZWR8ZmFpbGVkIHRvIGZldGNofG5ldHdvcmtlcnJvciB3aGVuIGF0dGVtcHRpbmcgdG8gZmV0Y2ggcmVzb3VyY2VcXC4/fGxvYWQgZmFpbGVkKSQvaTtcblxuLyoqIEVycm9yIG5hbWVzIHRoYXQgc2F5IGEgdmFsaWRhdGlvbiBmYWlsZWQg4oCUIHJldHJ5aW5nIHRoZSBzYW1lIGlucHV0IGNhbm5vdCBzdWNjZWVkLiAqL1xuY29uc3QgVkFMSURBVElPTl9OQU1FUzogUmVhZG9ubHlTZXQ8c3RyaW5nPiA9IG5ldyBTZXQoWydWYWxpZGF0aW9uRXJyb3InLCAnWm9kRXJyb3InLCAnSW5wdXRWYWxpZGF0aW9uRXJyb3InXSk7XG5cbi8qKiBFcnJvciBuYW1lcyBvZiBhbiBhYm9ydCBvciBhIHRpbWVvdXQgdGhhdCBzb21lIE9USEVSIHNpZ25hbCByYWlzZWQgKHRoZSBydW4ncyBvd24gZW5kcyBhcyBvdXRjb21lIGAnYWJvcnRlZCdgKS4gKi9cbmNvbnN0IFRSQU5TUE9SVF9BQk9SVF9OQU1FUzogUmVhZG9ubHlTZXQ8c3RyaW5nPiA9IG5ldyBTZXQoWydBYm9ydEVycm9yJywgJ1RpbWVvdXRFcnJvciddKTtcblxuLyoqXG4gKiBUaGUgY2F0ZWdvcnkgb2YgYW4gYXR0ZW1wdCdzIGZhaWx1cmUuIGBvdXRjb21lYCBpcyBob3cgdGhlIGF0dGVtcHQgZW5kZWQgKGRlZmF1bHQgYCdmYWlsZWQnYCk6IGl0IGRlY2lkZXNcbiAqIGAndGltZW91dCdgICh0aGUgYXR0ZW1wdCdzIG93biB0aW1lcikgYW5kIGAndW5rbm93bidgICh0aGUgcnVuJ3Mgc2lnbmFsKSBiZWZvcmUgdGhlIGVycm9yIGlzIHJlYWQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBlcnJvckNhdGVnb3J5KGVycm9yOiB1bmtub3duLCBvdXRjb21lOiBBdHRlbXB0T3V0Y29tZSA9ICdmYWlsZWQnKTogQXR0ZW1wdENhdGVnb3J5IHtcbiAgaWYgKG91dGNvbWUgPT09ICd0aW1lb3V0JykgcmV0dXJuICd0aW1lb3V0JztcbiAgaWYgKG91dGNvbWUgPT09ICdhYm9ydGVkJykgcmV0dXJuICd1bmtub3duJztcbiAgdHJ5IHtcbiAgICByZXR1cm4gY2F0ZWdvcnlPZihlcnJvcik7XG4gIH0gY2F0Y2gge1xuICAgIHJldHVybiAndW5rbm93bic7XG4gIH1cbn1cblxuLyoqXG4gKiBAaW50ZXJuYWwgVGVybWluYWwgb3duZXJzaGlwIHByZXNlcnZlcyBhIHByb2R1Y2VyJ3Mga25vd24gY2F0ZWdvcnkuIEFuXG4gKiB1bnJlc29sdmVkIGVmZmVjdCBpcyB1bmtub3duLCBuZXZlciB0aGUgY2F0ZWdvcnkgb2YgaXRzIHBoeXNpY2FsIGNhdXNlLlxuICogVGhpcyBkb2VzIG5vdCByZXdyaXRlIGhpc3RvcmljYWwgYXR0ZW1wdCBjYXRlZ29yaWVzIG9yIHJlLXJlYWQgYSBrbm93biBvbmUuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiB0ZXJtaW5hbENhdGVnb3J5KGVycm9yOiB1bmtub3duLCBrbm93bj86IEF0dGVtcHRDYXRlZ29yeSk6IEF0dGVtcHRDYXRlZ29yeSB7XG4gIHRyeSB7XG4gICAgaWYgKGVycm9yIGluc3RhbmNlb2YgVW5rbm93bkVmZmVjdEVycm9yKSByZXR1cm4gJ3Vua25vd24nO1xuICAgIC8vIENKUyBhbmQgRVNNIGhhdmUgZGlzdGluY3QgY29uc3RydWN0b3JzLiBBIGRlY2xhcmVkIG93biBEQVRBIG5hbWUgbWF5XG4gICAgLy8gb25seSByZWR1Y2UgY2VydGFpbnR5IHRvIHVua25vd247IG5ldmVyIGV4ZWN1dGUgYW4gZXJyb3IncyBuYW1lIGdldHRlclxuICAgIC8vIG9yIHByb21vdGUgaXRzIHBoeXNpY2FsIGNhdXNlIHRvIGEga25vd24gb3V0Y29tZSBhY3Jvc3MgbW9kdWxlIGNvcGllcy5cbiAgICBpZiAoZXJyb3IgIT09IG51bGwgJiYgKHR5cGVvZiBlcnJvciA9PT0gJ29iamVjdCcgfHwgdHlwZW9mIGVycm9yID09PSAnZnVuY3Rpb24nKSkge1xuICAgICAgY29uc3QgbmFtZSA9IE9iamVjdC5nZXRPd25Qcm9wZXJ0eURlc2NyaXB0b3IoZXJyb3IsICduYW1lJyk7XG4gICAgICBpZiAobmFtZSAmJiBPYmplY3QucHJvdG90eXBlLmhhc093blByb3BlcnR5LmNhbGwobmFtZSwgJ3ZhbHVlJykgJiYgbmFtZS52YWx1ZSA9PT0gJ1Vua25vd25FZmZlY3RFcnJvcicpIHtcbiAgICAgICAgcmV0dXJuICd1bmtub3duJztcbiAgICAgIH1cbiAgICB9XG4gIH0gY2F0Y2gge1xuICAgIHJldHVybiBrbm93biA/PyAndW5rbm93bic7XG4gIH1cbiAgcmV0dXJuIGtub3duID8/IGVycm9yQ2F0ZWdvcnkoZXJyb3IpO1xufVxuXG5mdW5jdGlvbiBjYXRlZ29yeU9mKGVycm9yOiB1bmtub3duKTogQXR0ZW1wdENhdGVnb3J5IHtcbiAgaWYgKGVycm9yIGluc3RhbmNlb2YgQXR0ZW1wdFRpbWVvdXRFcnJvcikgcmV0dXJuICd0aW1lb3V0JztcbiAgaWYgKGVycm9yID09PSBudWxsIHx8ICh0eXBlb2YgZXJyb3IgIT09ICdvYmplY3QnICYmIHR5cGVvZiBlcnJvciAhPT0gJ2Z1bmN0aW9uJykpIHJldHVybiAndW5rbm93bic7XG4gIGNvbnN0IGZpZWxkcyA9IGVycm9yIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+O1xuXG4gIGNvbnN0IHN0YXR1cyA9IG51bWJlckZpZWxkKGZpZWxkcywgJ3N0YXR1cycpID8/IG51bWJlckZpZWxkKGZpZWxkcywgJ3N0YXR1c0NvZGUnKTtcbiAgY29uc3QgZGVjbGFyZXNSZXRyeUFmdGVyID0gaXNXYWl0KGZpZWxkcy5yZXRyeUFmdGVyTXMpIHx8IGlzV2FpdChmaWVsZHMucmV0cnlBZnRlclNlY29uZHMpO1xuICBpZiAoc3RhdHVzID09PSA0MjkgfHwgZGVjbGFyZXNSZXRyeUFmdGVyKSByZXR1cm4gJ3JhdGUtbGltaXRlZCc7XG4gIGlmIChzdGF0dXMgIT09IHVuZGVmaW5lZCAmJiBzdGF0dXMgPj0gNTAwICYmIHN0YXR1cyA8PSA1OTkpIHJldHVybiAnc2VydmVyJztcbiAgaWYgKHN0YXR1cyA9PT0gNDAxIHx8IHN0YXR1cyA9PT0gNDAzKSByZXR1cm4gJ2F1dGgnO1xuICBpZiAoc3RhdHVzICE9PSB1bmRlZmluZWQgJiYgc3RhdHVzID49IDQwMCAmJiBzdGF0dXMgPD0gNDk5KSByZXR1cm4gJ3Blcm1hbmVudCc7XG5cbiAgaWYgKGZpZWxkcy5yZXRyeWFibGUgPT09IGZhbHNlKSByZXR1cm4gJ3Blcm1hbmVudCc7XG4gIGlmIChlcnJvciBpbnN0YW5jZW9mIElucHV0VmFsaWRhdGlvbkVycm9yKSByZXR1cm4gJ3Blcm1hbmVudCc7XG4gIGNvbnN0IG5hbWUgPSB0eXBlb2YgZmllbGRzLm5hbWUgPT09ICdzdHJpbmcnID8gZmllbGRzLm5hbWUgOiB1bmRlZmluZWQ7XG4gIGlmIChuYW1lICE9PSB1bmRlZmluZWQgJiYgVkFMSURBVElPTl9OQU1FUy5oYXMobmFtZSkpIHJldHVybiAncGVybWFuZW50JztcblxuICBpZiAoc3RhdHVzID09PSB1bmRlZmluZWQgJiYgaXNUcmFuc3BvcnRGYWlsdXJlKGZpZWxkcywgbmFtZSkpIHJldHVybiAnbmV0d29yayc7XG4gIHJldHVybiAndW5rbm93bic7XG59XG5cbmZ1bmN0aW9uIGlzVHJhbnNwb3J0RmFpbHVyZShmaWVsZHM6IFJlY29yZDxzdHJpbmcsIHVua25vd24+LCBuYW1lOiBzdHJpbmcgfCB1bmRlZmluZWQpOiBib29sZWFuIHtcbiAgaWYgKGhhc05ldHdvcmtDb2RlKGZpZWxkcy5jb2RlKSkgcmV0dXJuIHRydWU7XG4gIGNvbnN0IGNhdXNlID0gZmllbGRzLmNhdXNlO1xuICBpZiAoY2F1c2UgIT09IG51bGwgJiYgdHlwZW9mIGNhdXNlID09PSAnb2JqZWN0JyAmJiBoYXNOZXR3b3JrQ29kZSgoY2F1c2UgYXMgUmVjb3JkPHN0cmluZywgdW5rbm93bj4pLmNvZGUpKSB7XG4gICAgcmV0dXJuIHRydWU7XG4gIH1cbiAgaWYgKG5hbWUgIT09IHVuZGVmaW5lZCAmJiBUUkFOU1BPUlRfQUJPUlRfTkFNRVMuaGFzKG5hbWUpKSByZXR1cm4gdHJ1ZTtcbiAgcmV0dXJuIGZpZWxkcyBpbnN0YW5jZW9mIFR5cGVFcnJvciAmJiB0eXBlb2YgZmllbGRzLm1lc3NhZ2UgPT09ICdzdHJpbmcnICYmIEZFVENIX0ZBSUxVUkUudGVzdChmaWVsZHMubWVzc2FnZSk7XG59XG5cbmZ1bmN0aW9uIGhhc05ldHdvcmtDb2RlKGNvZGU6IHVua25vd24pOiBib29sZWFuIHtcbiAgcmV0dXJuIHR5cGVvZiBjb2RlID09PSAnc3RyaW5nJyAmJiBORVRXT1JLX0NPREVTLmhhcyhjb2RlKTtcbn1cblxuZnVuY3Rpb24gbnVtYmVyRmllbGQoZmllbGRzOiBSZWNvcmQ8c3RyaW5nLCB1bmtub3duPiwga2V5OiAnc3RhdHVzJyB8ICdzdGF0dXNDb2RlJyk6IG51bWJlciB8IHVuZGVmaW5lZCB7XG4gIGNvbnN0IHZhbHVlID0gZmllbGRzW2tleV07XG4gIHJldHVybiB0eXBlb2YgdmFsdWUgPT09ICdudW1iZXInICYmIE51bWJlci5pc0Zpbml0ZSh2YWx1ZSkgPyB2YWx1ZSA6IHVuZGVmaW5lZDtcbn1cblxuZnVuY3Rpb24gaXNXYWl0KHZhbHVlOiB1bmtub3duKTogYm9vbGVhbiB7XG4gIHJldHVybiB0eXBlb2YgdmFsdWUgPT09ICdudW1iZXInICYmIE51bWJlci5pc0Zpbml0ZSh2YWx1ZSkgJiYgdmFsdWUgPj0gMDtcbn1cbiJdfQ==

package/dist/esm/lib/attempt/correlation.d.ts

@@ -0,0 +1,95 @@
+/**
+ * attempt/correlation.ts — the run's correlation: the W3C `traceparent` codec and the ONE resolution of the env
+ * into a `RunCorrelation` (design docs/design/2026-10-time-and-failure-evidence.md §3.4, packet P4).
+ *
+ * THREAT MODEL. A `traceparent` comes from whoever sent the request. So:
+ *   - it is read STRICTLY to the W3C Trace Context grammar (`version-traceid-parentid-flags`, lowercase hex) and
+ *     anything else is refused by a NAMED reason (`TraceparentError.reason`) — the message never repeats the
+ *     header, and the error holds no copy of it;
+ *   - what the run keeps is the canonical form of what was parsed (`formatTraceparent`), never the received
+ *     bytes — a future version's tail is dropped;
+ *   - it is correlation only: a name the record carries so a run can be found from a trace. Nothing in the
+ *     library treats it as identity or authorisation.
+ *
+ * W3C forward compatibility: a version other than `00` (and never `ff`) is read by its first four fields; a
+ * longer header must continue with `-`. Version `00` is exactly 55 characters. A header longer than
+ * {@link MAX_HEADER_LENGTH} is refused before it is scanned.
+ */
+import type { RunCorrelation } from './types.js';
+/** Why a `traceparent` was refused — a NAME, so a caller can branch on it without reading a message. */
+export type TraceparentRefusal = 'not-a-string' | 'length' | 'version' | 'characters' | 'zero-trace-id' | 'zero-parent-id';
+/** A parsed `traceparent`: the W3C trace-id, the parent-id (the caller's unit of work), and its trace-flags. */
+export interface ParsedTraceparent {
+    /** 32 lowercase hex, not all zeros. */
+    readonly traceId: string;
+    /** The W3C parent-id — 16 lowercase hex, not all zeros. The library's word for it is "operation". */
+    readonly operationId: string;
+    /** Bit 0 of `flags`. */
+    readonly sampled: boolean;
+    /** The trace-flags byte as received — 2 lowercase hex — so a re-format keeps every bit (W3C level 2's random). */
+    readonly flags: string;
+}
+/**
+ * What `formatTraceparent` writes from. `flags` (2 lowercase hex) is the trace-flags byte, `'00'` when absent;
+ * `sampled`, when given, sets or clears its bit 0.
+ */
+export interface TraceparentFields {
+    readonly traceId: string;
+    readonly operationId: string;
+    readonly sampled?: boolean;
+    readonly flags?: string;
+}
+/** The longest header read at all (a future version may append fields; nothing legitimate is near this). */
+export declare const MAX_HEADER_LENGTH = 256;
+/** A `traceparent` the library will not read. The header itself is never in the message or on the error. */
+export declare class TraceparentError extends Error {
+    readonly reason: TraceparentRefusal;
+    constructor(reason: TraceparentRefusal);
+}
+/**
+ * Parse a W3C `traceparent` header strictly. Returns a frozen {@link ParsedTraceparent}; throws a
+ * {@link TraceparentError} naming the first rule the header breaks.
+ *
+ * @example
+ * parseTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+ * // { traceId: '4bf92f3577b34da6a3ce929d0e0e4736', operationId: '00f067aa0ba902b7', sampled: true, flags: '01' }
+ */
+export declare function parseTraceparent(header: unknown): ParsedTraceparent;
+/**
+ * Write a version-00 `traceparent` — for an outbound call that continues this run's trace. Both ids must be W3C
+ * ids and `flags` a byte of 2 lowercase hex (refused by name otherwise, like a parse); `sampled`, when given,
+ * sets or clears bit 0 of the flags. `formatTraceparent(parseTraceparent(h))` is `h` for any valid version-00 `h`.
+ *
+ * @example
+ * formatTraceparent({ traceId, operationId: mySpanId, sampled: true }); // '00-<traceId>-<mySpanId>-01'
+ */
+export declare function formatTraceparent(fields: TraceparentFields): string;
+/** The env fields correlation reads — structural, so this L5 file names nothing of the engine's `ExecutionEnv`. */
+export interface CorrelationEnv {
+    readonly traceparent?: unknown;
+    readonly traceId?: unknown;
+    readonly operationId?: unknown;
+}
+/**
+ * Admit a leg's env ONCE (called by `FlowChartExecutor · run` / `resume` before anything moves): a single
+ * own-property snapshot of it — every getter runs once, nothing is read off the prototype — and the correlation
+ * resolved from that snapshot. In the snapshot the stages see (`$getEnv()`), `traceparent` is exactly
+ * `correlation.traceparent` — the canonical header of the effective ids, or no key when the run's correlation has
+ * none — so stage code never holds the received bytes, nor a header naming another trace than the record.
+ * `env` is `undefined` exactly when none was given.
+ */
+export declare function admitRunEnv<E extends object>(env: E | undefined): {
+    readonly env: E | undefined;
+    readonly correlation: RunCorrelation | undefined;
+};
+/**
+ * The ONE resolution of a leg's correlation from its env. Only OWN fields count. `traceparent` is parsed once (a
+ * bad header refuses the leg — explicit ids do not rescue it); explicit `traceId` / `operationId` win over the
+ * header's and must be 1–256 printable ASCII characters (refused by field name, never echoed); an empty one is
+ * no id. Everything of the header — its parent-id as the operation, `sampled`, `traceparent` — rides only while
+ * the trace IS the header's, and `traceparent` is rebuilt from the EFFECTIVE ids with the header's flags
+ * (omitted when the operation is not a W3C parent-id), so the record never names one trace and files or
+ * propagates another's. Returns `undefined` when there is no trace id at all — and refuses
+ * an `operationId` with no trace to belong to.
+ */
+export declare function resolveCorrelation(env: CorrelationEnv | undefined): RunCorrelation | undefined;

package/dist/esm/lib/attempt/correlation.js

@@ -0,0 +1,178 @@
+/**
+ * attempt/correlation.ts — the run's correlation: the W3C `traceparent` codec and the ONE resolution of the env
+ * into a `RunCorrelation` (design docs/design/2026-10-time-and-failure-evidence.md §3.4, packet P4).
+ *
+ * THREAT MODEL. A `traceparent` comes from whoever sent the request. So:
+ *   - it is read STRICTLY to the W3C Trace Context grammar (`version-traceid-parentid-flags`, lowercase hex) and
+ *     anything else is refused by a NAMED reason (`TraceparentError.reason`) — the message never repeats the
+ *     header, and the error holds no copy of it;
+ *   - what the run keeps is the canonical form of what was parsed (`formatTraceparent`), never the received
+ *     bytes — a future version's tail is dropped;
+ *   - it is correlation only: a name the record carries so a run can be found from a trace. Nothing in the
+ *     library treats it as identity or authorisation.
+ *
+ * W3C forward compatibility: a version other than `00` (and never `ff`) is read by its first four fields; a
+ * longer header must continue with `-`. Version `00` is exactly 55 characters. A header longer than
+ * {@link MAX_HEADER_LENGTH} is refused before it is scanned.
+ */
+/** The longest header read at all (a future version may append fields; nothing legitimate is near this). */
+export const MAX_HEADER_LENGTH = 256;
+/** A version-00 header, exactly. */
+const V00_LENGTH = 55;
+const WHY = {
+    'not-a-string': 'it is not a string',
+    length: 'its length is not a W3C traceparent length (55 characters for version 00)',
+    version: 'its version is not two lowercase hex digits other than ff',
+    characters: 'it is not lowercase hex fields in the W3C layout version-traceid-parentid-flags',
+    'zero-trace-id': 'its trace-id is all zeros',
+    'zero-parent-id': 'its parent-id is all zeros',
+};
+/** A `traceparent` the library will not read. The header itself is never in the message or on the error. */
+export class TraceparentError extends Error {
+    reason;
+    constructor(reason) {
+        super(`traceparent refused (${reason}): ${WHY[reason]}`);
+        this.name = 'TraceparentError';
+        this.reason = reason;
+    }
+}
+const HEX2 = /^[0-9a-f]{2}$/;
+const HEX16 = /^[0-9a-f]{16}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+const ZEROS = /^0+$/;
+/**
+ * Parse a W3C `traceparent` header strictly. Returns a frozen {@link ParsedTraceparent}; throws a
+ * {@link TraceparentError} naming the first rule the header breaks.
+ *
+ * @example
+ * parseTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+ * // { traceId: '4bf92f3577b34da6a3ce929d0e0e4736', operationId: '00f067aa0ba902b7', sampled: true, flags: '01' }
+ */
+export function parseTraceparent(header) {
+    if (typeof header !== 'string')
+        throw new TraceparentError('not-a-string');
+    if (header.length < V00_LENGTH || header.length > MAX_HEADER_LENGTH)
+        throw new TraceparentError('length');
+    const version = header.slice(0, 2);
+    if (!HEX2.test(version) || version === 'ff')
+        throw new TraceparentError('version');
+    if (version === '00' && header.length !== V00_LENGTH)
+        throw new TraceparentError('length');
+    const traceId = header.slice(3, 35);
+    const operationId = header.slice(36, 52);
+    const flags = header.slice(53, 55);
+    const laidOut = header[2] === '-' && header[35] === '-' && header[52] === '-';
+    const tailOk = header.length === V00_LENGTH || header[V00_LENGTH] === '-';
+    if (!laidOut || !tailOk || !HEX32.test(traceId) || !HEX16.test(operationId) || !HEX2.test(flags)) {
+        throw new TraceparentError('characters');
+    }
+    if (ZEROS.test(traceId))
+        throw new TraceparentError('zero-trace-id');
+    if (ZEROS.test(operationId))
+        throw new TraceparentError('zero-parent-id');
+    return Object.freeze({ traceId, operationId, sampled: (parseInt(flags, 16) & 1) === 1, flags });
+}
+/**
+ * Write a version-00 `traceparent` — for an outbound call that continues this run's trace. Both ids must be W3C
+ * ids and `flags` a byte of 2 lowercase hex (refused by name otherwise, like a parse); `sampled`, when given,
+ * sets or clears bit 0 of the flags. `formatTraceparent(parseTraceparent(h))` is `h` for any valid version-00 `h`.
+ *
+ * @example
+ * formatTraceparent({ traceId, operationId: mySpanId, sampled: true }); // '00-<traceId>-<mySpanId>-01'
+ */
+export function formatTraceparent(fields) {
+    const { traceId, operationId } = fields;
+    if (typeof traceId !== 'string' || typeof operationId !== 'string')
+        throw new TraceparentError('not-a-string');
+    if (!HEX32.test(traceId) || !HEX16.test(operationId))
+        throw new TraceparentError('characters');
+    if (ZEROS.test(traceId))
+        throw new TraceparentError('zero-trace-id');
+    if (ZEROS.test(operationId))
+        throw new TraceparentError('zero-parent-id');
+    return `00-${traceId}-${operationId}-${flagsOf(fields)}`;
+}
+/** The trace-flags byte to write: the given one (or `00`), bit 0 set or cleared by `sampled` when it is given. */
+function flagsOf(fields) {
+    const { flags = '00', sampled } = fields;
+    if (typeof flags !== 'string')
+        throw new TraceparentError('not-a-string');
+    if (!HEX2.test(flags))
+        throw new TraceparentError('characters');
+    if (sampled === undefined)
+        return flags;
+    const byte = sampled ? parseInt(flags, 16) | 1 : parseInt(flags, 16) & 0xfe;
+    return byte.toString(16).padStart(2, '0');
+}
+/** An explicit id: 1–256 printable ASCII characters, no space — a name a log line or an exporter can carry. */
+const EXPLICIT_ID = /^[\x21-\x7e]{1,256}$/;
+/**
+ * Admit a leg's env ONCE (called by `FlowChartExecutor · run` / `resume` before anything moves): a single
+ * own-property snapshot of it — every getter runs once, nothing is read off the prototype — and the correlation
+ * resolved from that snapshot. In the snapshot the stages see (`$getEnv()`), `traceparent` is exactly
+ * `correlation.traceparent` — the canonical header of the effective ids, or no key when the run's correlation has
+ * none — so stage code never holds the received bytes, nor a header naming another trace than the record.
+ * `env` is `undefined` exactly when none was given.
+ */
+export function admitRunEnv(env) {
+    if (env === undefined || env === null)
+        return { env: undefined, correlation: undefined };
+    const snapshot = { ...env };
+    const correlation = resolveParsed(snapshot);
+    if (correlation?.traceparent !== undefined)
+        snapshot.traceparent = correlation.traceparent;
+    else if (snapshot.traceparent !== undefined)
+        delete snapshot.traceparent; // a header the record does not carry
+    return { env: snapshot, correlation };
+}
+/**
+ * The ONE resolution of a leg's correlation from its env. Only OWN fields count. `traceparent` is parsed once (a
+ * bad header refuses the leg — explicit ids do not rescue it); explicit `traceId` / `operationId` win over the
+ * header's and must be 1–256 printable ASCII characters (refused by field name, never echoed); an empty one is
+ * no id. Everything of the header — its parent-id as the operation, `sampled`, `traceparent` — rides only while
+ * the trace IS the header's, and `traceparent` is rebuilt from the EFFECTIVE ids with the header's flags
+ * (omitted when the operation is not a W3C parent-id), so the record never names one trace and files or
+ * propagates another's. Returns `undefined` when there is no trace id at all — and refuses
+ * an `operationId` with no trace to belong to.
+ */
+export function resolveCorrelation(env) {
+    if (env === undefined || env === null)
+        return undefined;
+    return resolveParsed({ ...env });
+}
+/** {@link resolveCorrelation} over an env already snapshotted (each field read once). */
+function resolveParsed(env) {
+    const raw = own(env, 'traceparent');
+    const header = raw === undefined ? undefined : parseTraceparent(raw);
+    const traceId = explicitId(own(env, 'traceId'), 'traceId') ?? header?.traceId;
+    const sameTrace = header !== undefined && traceId === header.traceId;
+    const operationId = explicitId(own(env, 'operationId'), 'operationId') ?? (sameTrace ? header.operationId : undefined);
+    if (traceId === undefined) {
+        if (operationId !== undefined) {
+            throw new TypeError('env.operationId needs a trace to belong to: give env.traceId or env.traceparent');
+        }
+        return undefined;
+    }
+    const propagable = sameTrace && operationId !== undefined && HEX16.test(operationId) && !ZEROS.test(operationId);
+    return Object.freeze({
+        traceId,
+        ...(operationId !== undefined && { operationId }),
+        ...(sameTrace && { sampled: header.sampled }),
+        ...(propagable && { traceparent: formatTraceparent({ traceId, operationId, flags: header.flags }) }),
+    });
+}
+/** An own field's value — a value inherited through the prototype is not the caller's. */
+function own(env, field) {
+    return Object.prototype.hasOwnProperty.call(env, field) ? env[field] : undefined;
+}
+function explicitId(value, field) {
+    if (value === undefined || value === '')
+        return undefined;
+    if (typeof value !== 'string')
+        throw new TypeError(`env.${field} must be a string`);
+    if (!EXPLICIT_ID.test(value)) {
+        throw new TypeError(`env.${field} refused: an id is 1–256 printable ASCII characters with no space`);
+    }
+    return value;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29ycmVsYXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvbGliL2F0dGVtcHQvY29ycmVsYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7R0FnQkc7QUFvQ0gsNEdBQTRHO0FBQzVHLE1BQU0sQ0FBQyxNQUFNLGlCQUFpQixHQUFHLEdBQUcsQ0FBQztBQUNyQyxvQ0FBb0M7QUFDcEMsTUFBTSxVQUFVLEdBQUcsRUFBRSxDQUFDO0FBRXRCLE1BQU0sR0FBRyxHQUFpRDtJQUN4RCxjQUFjLEVBQUUsb0JBQW9CO0lBQ3BDLE1BQU0sRUFBRSwyRUFBMkU7SUFDbkYsT0FBTyxFQUFFLDJEQUEyRDtJQUNwRSxVQUFVLEVBQUUsaUZBQWlGO0lBQzdGLGVBQWUsRUFBRSwyQkFBMkI7SUFDNUMsZ0JBQWdCLEVBQUUsNEJBQTRCO0NBQy9DLENBQUM7QUFFRiw0R0FBNEc7QUFDNUcsTUFBTSxPQUFPLGdCQUFpQixTQUFRLEtBQUs7SUFDaEMsTUFBTSxDQUFxQjtJQUVwQyxZQUFZLE1BQTBCO1FBQ3BDLEtBQUssQ0FBQyx3QkFBd0IsTUFBTSxNQUFNLEdBQUcsQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDLENBQUM7UUFDekQsSUFBSSxDQUFDLElBQUksR0FBRyxrQkFBa0IsQ0FBQztRQUMvQixJQUFJLENBQUMsTUFBTSxHQUFHLE1BQU0sQ0FBQztJQUN2QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLElBQUksR0FBRyxlQUFlLENBQUM7QUFDN0IsTUFBTSxLQUFLLEdBQUcsZ0JBQWdCLENBQUM7QUFDL0IsTUFBTSxLQUFLLEdBQUcsZ0JBQWdCLENBQUM7QUFDL0IsTUFBTSxLQUFLLEdBQUcsTUFBTSxDQUFDO0FBRXJCOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLFVBQVUsZ0JBQWdCLENBQUMsTUFBZTtJQUM5QyxJQUFJLE9BQU8sTUFBTSxLQUFLLFFBQVE7UUFBRSxNQUFNLElBQUksZ0JBQWdCLENBQUMsY0FBYyxDQUFDLENBQUM7SUFDM0UsSUFBSSxNQUFNLENBQUMsTUFBTSxHQUFHLFVBQVUsSUFBSSxNQUFNLENBQUMsTUFBTSxHQUFHLGlCQUFpQjtRQUFFLE1BQU0sSUFBSSxnQkFBZ0IsQ0FBQyxRQUFRLENBQUMsQ0FBQztJQUMxRyxNQUFNLE9BQU8sR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQztJQUNuQyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxPQUFPLEtBQUssSUFBSTtRQUFFLE1BQU0sSUFBSSxnQkFBZ0IsQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUNuRixJQUFJLE9BQU8sS0FBSyxJQUFJLElBQUksTUFBTSxDQUFDLE1BQU0sS0FBSyxVQUFVO1FBQUUsTUFBTSxJQUFJLGdCQUFnQixDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBRTNGLE1BQU0sT0FBTyxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDO0lBQ3BDLE1BQU0sV0FBVyxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsRUFBRSxFQUFFLEVBQUUsQ0FBQyxDQUFDO0lBQ3pDLE1BQU0sS0FBSyxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsRUFBRSxFQUFFLEVBQUUsQ0FBQyxDQUFDO0lBQ25DLE1BQU0sT0FBTyxHQUFHLE1BQU0sQ0FBQyxDQUFDLENBQUMsS0FBSyxHQUFHLElBQUksTUFBTSxDQUFDLEVBQUUsQ0FBQyxLQUFLLEdBQUcsSUFBSSxNQUFNLENBQUMsRUFBRSxDQUFDLEtBQUssR0FBRyxDQUFDO0lBQzlFLE1BQU0sTUFBTSxHQUFHLE1BQU0sQ0FBQyxNQUFNLEtBQUssVUFBVSxJQUFJLE1BQU0sQ0FBQyxVQUFVLENBQUMsS0FBSyxHQUFHLENBQUM7SUFDMUUsSUFBSSxDQUFDLE9BQU8sSUFBSSxDQUFDLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDO1FBQ2pHLE1BQU0sSUFBSSxnQkFBZ0IsQ0FBQyxZQUFZLENBQUMsQ0FBQztJQUMzQyxDQUFDO0lBQ0QsSUFBSSxLQUFLLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQztRQUFFLE1BQU0sSUFBSSxnQkFBZ0IsQ0FBQyxlQUFlLENBQUMsQ0FBQztJQUNyRSxJQUFJLEtBQUssQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDO1FBQUUsTUFBTSxJQUFJLGdCQUFnQixDQUFDLGdCQUFnQixDQUFDLENBQUM7SUFFMUUsT0FBTyxNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRSxPQUFPLEVBQUUsQ0FBQyxRQUFRLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxLQUFLLENBQUMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxDQUFDO0FBQ2xHLENBQUM7QUFFRDs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxVQUFVLGlCQUFpQixDQUFDLE1BQXlCO0lBQ3pELE1BQU0sRUFBRSxPQUFPLEVBQUUsV0FBVyxFQUFFLEdBQUcsTUFBTSxDQUFDO0lBQ3hDLElBQUksT0FBTyxPQUFPLEtBQUssUUFBUSxJQUFJLE9BQU8sV0FBVyxLQUFLLFFBQVE7UUFBRSxNQUFNLElBQUksZ0JBQWdCLENBQUMsY0FBYyxDQUFDLENBQUM7SUFDL0csSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLFdBQVcsQ0FBQztRQUFFLE1BQU0sSUFBSSxnQkFBZ0IsQ0FBQyxZQUFZLENBQUMsQ0FBQztJQUMvRixJQUFJLEtBQUssQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDO1FBQUUsTUFBTSxJQUFJLGdCQUFnQixDQUFDLGVBQWUsQ0FBQyxDQUFDO0lBQ3JFLElBQUksS0FBSyxDQUFDLElBQUksQ0FBQyxXQUFXLENBQUM7UUFBRSxNQUFNLElBQUksZ0JBQWdCLENBQUMsZ0JBQWdCLENBQUMsQ0FBQztJQUMxRSxPQUFPLE1BQU0sT0FBTyxJQUFJLFdBQVcsSUFBSSxPQUFPLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQztBQUMzRCxDQUFDO0FBRUQsa0hBQWtIO0FBQ2xILFNBQVMsT0FBTyxDQUFDLE1BQXlCO0lBQ3hDLE1BQU0sRUFBRSxLQUFLLEdBQUcsSUFBSSxFQUFFLE9BQU8sRUFBRSxHQUFHLE1BQU0sQ0FBQztJQUN6QyxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVE7UUFBRSxNQUFNLElBQUksZ0JBQWdCLENBQUMsY0FBYyxDQUFDLENBQUM7SUFDMUUsSUFBSSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDO1FBQUUsTUFBTSxJQUFJLGdCQUFnQixDQUFDLFlBQVksQ0FBQyxDQUFDO0lBQ2hFLElBQUksT0FBTyxLQUFLLFNBQVM7UUFBRSxPQUFPLEtBQUssQ0FBQztJQUN4QyxNQUFNLElBQUksR0FBRyxPQUFPLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxRQUFRLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxHQUFHLElBQUksQ0FBQztJQUM1RSxPQUFPLElBQUksQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDLENBQUMsUUFBUSxDQUFDLENBQUMsRUFBRSxHQUFHLENBQUMsQ0FBQztBQUM1QyxDQUFDO0FBU0QsK0dBQStHO0FBQy9HLE1BQU0sV0FBVyxHQUFHLHNCQUFzQixDQUFDO0FBRTNDOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLFVBQVUsV0FBVyxDQUN6QixHQUFrQjtJQUVsQixJQUFJLEdBQUcsS0FBSyxTQUFTLElBQUksR0FBRyxLQUFLLElBQUk7UUFBRSxPQUFPLEVBQUUsR0FBRyxFQUFFLFNBQVMsRUFBRSxXQUFXLEVBQUUsU0FBUyxFQUFFLENBQUM7SUFDekYsTUFBTSxRQUFRLEdBQUcsRUFBRSxHQUFHLEdBQUcsRUFBbUMsQ0FBQztJQUM3RCxNQUFNLFdBQVcsR0FBRyxhQUFhLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDNUMsSUFBSSxXQUFXLEVBQUUsV0FBVyxLQUFLLFNBQVM7UUFBRSxRQUFRLENBQUMsV0FBVyxHQUFHLFdBQVcsQ0FBQyxXQUFXLENBQUM7U0FDdEYsSUFBSSxRQUFRLENBQUMsV0FBVyxLQUFLLFNBQVM7UUFBRSxPQUFPLFFBQVEsQ0FBQyxXQUFXLENBQUMsQ0FBQyxxQ0FBcUM7SUFDL0csT0FBTyxFQUFFLEdBQUcsRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLENBQUM7QUFDeEMsQ0FBQztBQUVEOzs7Ozs7Ozs7R0FTRztBQUNILE1BQU0sVUFBVSxrQkFBa0IsQ0FBQyxHQUErQjtJQUNoRSxJQUFJLEdBQUcsS0FBSyxTQUFTLElBQUksR0FBRyxLQUFLLElBQUk7UUFBRSxPQUFPLFNBQVMsQ0FBQztJQUN4RCxPQUFPLGFBQWEsQ0FBQyxFQUFFLEdBQUcsR0FBRyxFQUFFLENBQUMsQ0FBQztBQUNuQyxDQUFDO0FBRUQseUZBQXlGO0FBQ3pGLFNBQVMsYUFBYSxDQUFDLEdBQW1CO0lBQ3hDLE1BQU0sR0FBRyxHQUFHLEdBQUcsQ0FBQyxHQUFHLEVBQUUsYUFBYSxDQUFDLENBQUM7SUFDcEMsTUFBTSxNQUFNLEdBQUcsR0FBRyxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxnQkFBZ0IsQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUNyRSxNQUFNLE9BQU8sR0FBRyxVQUFVLENBQUMsR0FBRyxDQUFDLEdBQUcsRUFBRSxTQUFTLENBQUMsRUFBRSxTQUFTLENBQUMsSUFBSSxNQUFNLEVBQUUsT0FBTyxDQUFDO0lBQzlFLE1BQU0sU0FBUyxHQUFHLE1BQU0sS0FBSyxTQUFTLElBQUksT0FBTyxLQUFLLE1BQU0sQ0FBQyxPQUFPLENBQUM7SUFDckUsTUFBTSxXQUFXLEdBQ2YsVUFBVSxDQUFDLEdBQUcsQ0FBQyxHQUFHLEVBQUUsYUFBYSxDQUFDLEVBQUUsYUFBYSxDQUFDLElBQUksQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDO0lBQ3JHLElBQUksT0FBTyxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQzFCLElBQUksV0FBVyxLQUFLLFNBQVMsRUFBRSxDQUFDO1lBQzlCLE1BQU0sSUFBSSxTQUFTLENBQUMsaUZBQWlGLENBQUMsQ0FBQztRQUN6RyxDQUFDO1FBQ0QsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztJQUNELE1BQU0sVUFBVSxHQUFHLFNBQVMsSUFBSSxXQUFXLEtBQUssU0FBUyxJQUFJLEtBQUssQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLFdBQVcsQ0FBQyxDQUFDO0lBQ2pILE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQztRQUNuQixPQUFPO1FBQ1AsR0FBRyxDQUFDLFdBQVcsS0FBSyxTQUFTLElBQUksRUFBRSxXQUFXLEVBQUUsQ0FBQztRQUNqRCxHQUFHLENBQUMsU0FBUyxJQUFJLEVBQUUsT0FBTyxFQUFFLE1BQU0sQ0FBQyxPQUFPLEVBQUUsQ0FBQztRQUM3QyxHQUFHLENBQUMsVUFBVSxJQUFJLEVBQUUsV0FBVyxFQUFFLGlCQUFpQixDQUFDLEVBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRSxLQUFLLEVBQUUsTUFBTSxDQUFDLEtBQUssRUFBRSxDQUFDLEVBQUUsQ0FBQztLQUNyRyxDQUFDLENBQUM7QUFDTCxDQUFDO0FBRUQsMEZBQTBGO0FBQzFGLFNBQVMsR0FBRyxDQUFDLEdBQW1CLEVBQUUsS0FBMkI7SUFDM0QsT0FBTyxNQUFNLENBQUMsU0FBUyxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxHQUFHLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQztBQUNuRixDQUFDO0FBRUQsU0FBUyxVQUFVLENBQUMsS0FBYyxFQUFFLEtBQWdDO0lBQ2xFLElBQUksS0FBSyxLQUFLLFNBQVMsSUFBSSxLQUFLLEtBQUssRUFBRTtRQUFFLE9BQU8sU0FBUyxDQUFDO0lBQzFELElBQUksT0FBTyxLQUFLLEtBQUssUUFBUTtRQUFFLE1BQU0sSUFBSSxTQUFTLENBQUMsT0FBTyxLQUFLLG1CQUFtQixDQUFDLENBQUM7SUFDcEYsSUFBSSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUM3QixNQUFNLElBQUksU0FBUyxDQUFDLE9BQU8sS0FBSyxtRUFBbUUsQ0FBQyxDQUFDO0lBQ3ZHLENBQUM7SUFDRCxPQUFPLEtBQUssQ0FBQztBQUNmLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIGF0dGVtcHQvY29ycmVsYXRpb24udHMg4oCUIHRoZSBydW4ncyBjb3JyZWxhdGlvbjogdGhlIFczQyBgdHJhY2VwYXJlbnRgIGNvZGVjIGFuZCB0aGUgT05FIHJlc29sdXRpb24gb2YgdGhlIGVudlxuICogaW50byBhIGBSdW5Db3JyZWxhdGlvbmAgKGRlc2lnbiBkb2NzL2Rlc2lnbi8yMDI2LTEwLXRpbWUtYW5kLWZhaWx1cmUtZXZpZGVuY2UubWQgwqczLjQsIHBhY2tldCBQNCkuXG4gKlxuICogVEhSRUFUIE1PREVMLiBBIGB0cmFjZXBhcmVudGAgY29tZXMgZnJvbSB3aG9ldmVyIHNlbnQgdGhlIHJlcXVlc3QuIFNvOlxuICogICAtIGl0IGlzIHJlYWQgU1RSSUNUTFkgdG8gdGhlIFczQyBUcmFjZSBDb250ZXh0IGdyYW1tYXIgKGB2ZXJzaW9uLXRyYWNlaWQtcGFyZW50aWQtZmxhZ3NgLCBsb3dlcmNhc2UgaGV4KSBhbmRcbiAqICAgICBhbnl0aGluZyBlbHNlIGlzIHJlZnVzZWQgYnkgYSBOQU1FRCByZWFzb24gKGBUcmFjZXBhcmVudEVycm9yLnJlYXNvbmApIOKAlCB0aGUgbWVzc2FnZSBuZXZlciByZXBlYXRzIHRoZVxuICogICAgIGhlYWRlciwgYW5kIHRoZSBlcnJvciBob2xkcyBubyBjb3B5IG9mIGl0O1xuICogICAtIHdoYXQgdGhlIHJ1biBrZWVwcyBpcyB0aGUgY2Fub25pY2FsIGZvcm0gb2Ygd2hhdCB3YXMgcGFyc2VkIChgZm9ybWF0VHJhY2VwYXJlbnRgKSwgbmV2ZXIgdGhlIHJlY2VpdmVkXG4gKiAgICAgYnl0ZXMg4oCUIGEgZnV0dXJlIHZlcnNpb24ncyB0YWlsIGlzIGRyb3BwZWQ7XG4gKiAgIC0gaXQgaXMgY29ycmVsYXRpb24gb25seTogYSBuYW1lIHRoZSByZWNvcmQgY2FycmllcyBzbyBhIHJ1biBjYW4gYmUgZm91bmQgZnJvbSBhIHRyYWNlLiBOb3RoaW5nIGluIHRoZVxuICogICAgIGxpYnJhcnkgdHJlYXRzIGl0IGFzIGlkZW50aXR5IG9yIGF1dGhvcmlzYXRpb24uXG4gKlxuICogVzNDIGZvcndhcmQgY29tcGF0aWJpbGl0eTogYSB2ZXJzaW9uIG90aGVyIHRoYW4gYDAwYCAoYW5kIG5ldmVyIGBmZmApIGlzIHJlYWQgYnkgaXRzIGZpcnN0IGZvdXIgZmllbGRzOyBhXG4gKiBsb25nZXIgaGVhZGVyIG11c3QgY29udGludWUgd2l0aCBgLWAuIFZlcnNpb24gYDAwYCBpcyBleGFjdGx5IDU1IGNoYXJhY3RlcnMuIEEgaGVhZGVyIGxvbmdlciB0aGFuXG4gKiB7QGxpbmsgTUFYX0hFQURFUl9MRU5HVEh9IGlzIHJlZnVzZWQgYmVmb3JlIGl0IGlzIHNjYW5uZWQuXG4gKi9cblxuaW1wb3J0IHR5cGUgeyBSdW5Db3JyZWxhdGlvbiB9IGZyb20gJy4vdHlwZXMuanMnO1xuXG4vKiogV2h5IGEgYHRyYWNlcGFyZW50YCB3YXMgcmVmdXNlZCDigJQgYSBOQU1FLCBzbyBhIGNhbGxlciBjYW4gYnJhbmNoIG9uIGl0IHdpdGhvdXQgcmVhZGluZyBhIG1lc3NhZ2UuICovXG5leHBvcnQgdHlwZSBUcmFjZXBhcmVudFJlZnVzYWwgPVxuICB8ICdub3QtYS1zdHJpbmcnXG4gIHwgJ2xlbmd0aCdcbiAgfCAndmVyc2lvbidcbiAgfCAnY2hhcmFjdGVycydcbiAgfCAnemVyby10cmFjZS1pZCdcbiAgfCAnemVyby1wYXJlbnQtaWQnO1xuXG4vKiogQSBwYXJzZWQgYHRyYWNlcGFyZW50YDogdGhlIFczQyB0cmFjZS1pZCwgdGhlIHBhcmVudC1pZCAodGhlIGNhbGxlcidzIHVuaXQgb2Ygd29yayksIGFuZCBpdHMgdHJhY2UtZmxhZ3MuICovXG5leHBvcnQgaW50ZXJmYWNlIFBhcnNlZFRyYWNlcGFyZW50IHtcbiAgLyoqIDMyIGxvd2VyY2FzZSBoZXgsIG5vdCBhbGwgemVyb3MuICovXG4gIHJlYWRvbmx5IHRyYWNlSWQ6IHN0cmluZztcbiAgLyoqIFRoZSBXM0MgcGFyZW50LWlkIOKAlCAxNiBsb3dlcmNhc2UgaGV4LCBub3QgYWxsIHplcm9zLiBUaGUgbGlicmFyeSdzIHdvcmQgZm9yIGl0IGlzIFwib3BlcmF0aW9uXCIuICovXG4gIHJlYWRvbmx5IG9wZXJhdGlvbklkOiBzdHJpbmc7XG4gIC8qKiBCaXQgMCBvZiBgZmxhZ3NgLiAqL1xuICByZWFkb25seSBzYW1wbGVkOiBib29sZWFuO1xuICAvKiogVGhlIHRyYWNlLWZsYWdzIGJ5dGUgYXMgcmVjZWl2ZWQg4oCUIDIgbG93ZXJjYXNlIGhleCDigJQgc28gYSByZS1mb3JtYXQga2VlcHMgZXZlcnkgYml0IChXM0MgbGV2ZWwgMidzIHJhbmRvbSkuICovXG4gIHJlYWRvbmx5IGZsYWdzOiBzdHJpbmc7XG59XG5cbi8qKlxuICogV2hhdCBgZm9ybWF0VHJhY2VwYXJlbnRgIHdyaXRlcyBmcm9tLiBgZmxhZ3NgICgyIGxvd2VyY2FzZSBoZXgpIGlzIHRoZSB0cmFjZS1mbGFncyBieXRlLCBgJzAwJ2Agd2hlbiBhYnNlbnQ7XG4gKiBgc2FtcGxlZGAsIHdoZW4gZ2l2ZW4sIHNldHMgb3IgY2xlYXJzIGl0cyBiaXQgMC5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBUcmFjZXBhcmVudEZpZWxkcyB7XG4gIHJlYWRvbmx5IHRyYWNlSWQ6IHN0cmluZztcbiAgcmVhZG9ubHkgb3BlcmF0aW9uSWQ6IHN0cmluZztcbiAgcmVhZG9ubHkgc2FtcGxlZD86IGJvb2xlYW47XG4gIHJlYWRvbmx5IGZsYWdzPzogc3RyaW5nO1xufVxuXG4vKiogVGhlIGxvbmdlc3QgaGVhZGVyIHJlYWQgYXQgYWxsIChhIGZ1dHVyZSB2ZXJzaW9uIG1heSBhcHBlbmQgZmllbGRzOyBub3RoaW5nIGxlZ2l0aW1hdGUgaXMgbmVhciB0aGlzKS4gKi9cbmV4cG9ydCBjb25zdCBNQVhfSEVBREVSX0xFTkdUSCA9IDI1Njtcbi8qKiBBIHZlcnNpb24tMDAgaGVhZGVyLCBleGFjdGx5LiAqL1xuY29uc3QgVjAwX0xFTkdUSCA9IDU1O1xuXG5jb25zdCBXSFk6IFJlYWRvbmx5PFJlY29yZDxUcmFjZXBhcmVudFJlZnVzYWwsIHN0cmluZz4+ID0ge1xuICAnbm90LWEtc3RyaW5nJzogJ2l0IGlzIG5vdCBhIHN0cmluZycsXG4gIGxlbmd0aDogJ2l0cyBsZW5ndGggaXMgbm90IGEgVzNDIHRyYWNlcGFyZW50IGxlbmd0aCAoNTUgY2hhcmFjdGVycyBmb3IgdmVyc2lvbiAwMCknLFxuICB2ZXJzaW9uOiAnaXRzIHZlcnNpb24gaXMgbm90IHR3byBsb3dlcmNhc2UgaGV4IGRpZ2l0cyBvdGhlciB0aGFuIGZmJyxcbiAgY2hhcmFjdGVyczogJ2l0IGlzIG5vdCBsb3dlcmNhc2UgaGV4IGZpZWxkcyBpbiB0aGUgVzNDIGxheW91dCB2ZXJzaW9uLXRyYWNlaWQtcGFyZW50aWQtZmxhZ3MnLFxuICAnemVyby10cmFjZS1pZCc6ICdpdHMgdHJhY2UtaWQgaXMgYWxsIHplcm9zJyxcbiAgJ3plcm8tcGFyZW50LWlkJzogJ2l0cyBwYXJlbnQtaWQgaXMgYWxsIHplcm9zJyxcbn07XG5cbi8qKiBBIGB0cmFjZXBhcmVudGAgdGhlIGxpYnJhcnkgd2lsbCBub3QgcmVhZC4gVGhlIGhlYWRlciBpdHNlbGYgaXMgbmV2ZXIgaW4gdGhlIG1lc3NhZ2Ugb3Igb24gdGhlIGVycm9yLiAqL1xuZXhwb3J0IGNsYXNzIFRyYWNlcGFyZW50RXJyb3IgZXh0ZW5kcyBFcnJvciB7XG4gIHJlYWRvbmx5IHJlYXNvbjogVHJhY2VwYXJlbnRSZWZ1c2FsO1xuXG4gIGNvbnN0cnVjdG9yKHJlYXNvbjogVHJhY2VwYXJlbnRSZWZ1c2FsKSB7XG4gICAgc3VwZXIoYHRyYWNlcGFyZW50IHJlZnVzZWQgKCR7cmVhc29ufSk6ICR7V0hZW3JlYXNvbl19YCk7XG4gICAgdGhpcy5uYW1lID0gJ1RyYWNlcGFyZW50RXJyb3InO1xuICAgIHRoaXMucmVhc29uID0gcmVhc29uO1xuICB9XG59XG5cbmNvbnN0IEhFWDIgPSAvXlswLTlhLWZdezJ9JC87XG5jb25zdCBIRVgxNiA9IC9eWzAtOWEtZl17MTZ9JC87XG5jb25zdCBIRVgzMiA9IC9eWzAtOWEtZl17MzJ9JC87XG5jb25zdCBaRVJPUyA9IC9eMCskLztcblxuLyoqXG4gKiBQYXJzZSBhIFczQyBgdHJhY2VwYXJlbnRgIGhlYWRlciBzdHJpY3RseS4gUmV0dXJucyBhIGZyb3plbiB7QGxpbmsgUGFyc2VkVHJhY2VwYXJlbnR9OyB0aHJvd3MgYVxuICoge0BsaW5rIFRyYWNlcGFyZW50RXJyb3J9IG5hbWluZyB0aGUgZmlyc3QgcnVsZSB0aGUgaGVhZGVyIGJyZWFrcy5cbiAqXG4gKiBAZXhhbXBsZVxuICogcGFyc2VUcmFjZXBhcmVudCgnMDAtNGJmOTJmMzU3N2IzNGRhNmEzY2U5MjlkMGUwZTQ3MzYtMDBmMDY3YWEwYmE5MDJiNy0wMScpO1xuICogLy8geyB0cmFjZUlkOiAnNGJmOTJmMzU3N2IzNGRhNmEzY2U5MjlkMGUwZTQ3MzYnLCBvcGVyYXRpb25JZDogJzAwZjA2N2FhMGJhOTAyYjcnLCBzYW1wbGVkOiB0cnVlLCBmbGFnczogJzAxJyB9XG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBwYXJzZVRyYWNlcGFyZW50KGhlYWRlcjogdW5rbm93bik6IFBhcnNlZFRyYWNlcGFyZW50IHtcbiAgaWYgKHR5cGVvZiBoZWFkZXIgIT09ICdzdHJpbmcnKSB0aHJvdyBuZXcgVHJhY2VwYXJlbnRFcnJvcignbm90LWEtc3RyaW5nJyk7XG4gIGlmIChoZWFkZXIubGVuZ3RoIDwgVjAwX0xFTkdUSCB8fCBoZWFkZXIubGVuZ3RoID4gTUFYX0hFQURFUl9MRU5HVEgpIHRocm93IG5ldyBUcmFjZXBhcmVudEVycm9yKCdsZW5ndGgnKTtcbiAgY29uc3QgdmVyc2lvbiA9IGhlYWRlci5zbGljZSgwLCAyKTtcbiAgaWYgKCFIRVgyLnRlc3QodmVyc2lvbikgfHwgdmVyc2lvbiA9PT0gJ2ZmJykgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ3ZlcnNpb24nKTtcbiAgaWYgKHZlcnNpb24gPT09ICcwMCcgJiYgaGVhZGVyLmxlbmd0aCAhPT0gVjAwX0xFTkdUSCkgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ2xlbmd0aCcpO1xuXG4gIGNvbnN0IHRyYWNlSWQgPSBoZWFkZXIuc2xpY2UoMywgMzUpO1xuICBjb25zdCBvcGVyYXRpb25JZCA9IGhlYWRlci5zbGljZSgzNiwgNTIpO1xuICBjb25zdCBmbGFncyA9IGhlYWRlci5zbGljZSg1MywgNTUpO1xuICBjb25zdCBsYWlkT3V0ID0gaGVhZGVyWzJdID09PSAnLScgJiYgaGVhZGVyWzM1XSA9PT0gJy0nICYmIGhlYWRlcls1Ml0gPT09ICctJztcbiAgY29uc3QgdGFpbE9rID0gaGVhZGVyLmxlbmd0aCA9PT0gVjAwX0xFTkdUSCB8fCBoZWFkZXJbVjAwX0xFTkdUSF0gPT09ICctJztcbiAgaWYgKCFsYWlkT3V0IHx8ICF0YWlsT2sgfHwgIUhFWDMyLnRlc3QodHJhY2VJZCkgfHwgIUhFWDE2LnRlc3Qob3BlcmF0aW9uSWQpIHx8ICFIRVgyLnRlc3QoZmxhZ3MpKSB7XG4gICAgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ2NoYXJhY3RlcnMnKTtcbiAgfVxuICBpZiAoWkVST1MudGVzdCh0cmFjZUlkKSkgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ3plcm8tdHJhY2UtaWQnKTtcbiAgaWYgKFpFUk9TLnRlc3Qob3BlcmF0aW9uSWQpKSB0aHJvdyBuZXcgVHJhY2VwYXJlbnRFcnJvcignemVyby1wYXJlbnQtaWQnKTtcblxuICByZXR1cm4gT2JqZWN0LmZyZWV6ZSh7IHRyYWNlSWQsIG9wZXJhdGlvbklkLCBzYW1wbGVkOiAocGFyc2VJbnQoZmxhZ3MsIDE2KSAmIDEpID09PSAxLCBmbGFncyB9KTtcbn1cblxuLyoqXG4gKiBXcml0ZSBhIHZlcnNpb24tMDAgYHRyYWNlcGFyZW50YCDigJQgZm9yIGFuIG91dGJvdW5kIGNhbGwgdGhhdCBjb250aW51ZXMgdGhpcyBydW4ncyB0cmFjZS4gQm90aCBpZHMgbXVzdCBiZSBXM0NcbiAqIGlkcyBhbmQgYGZsYWdzYCBhIGJ5dGUgb2YgMiBsb3dlcmNhc2UgaGV4IChyZWZ1c2VkIGJ5IG5hbWUgb3RoZXJ3aXNlLCBsaWtlIGEgcGFyc2UpOyBgc2FtcGxlZGAsIHdoZW4gZ2l2ZW4sXG4gKiBzZXRzIG9yIGNsZWFycyBiaXQgMCBvZiB0aGUgZmxhZ3MuIGBmb3JtYXRUcmFjZXBhcmVudChwYXJzZVRyYWNlcGFyZW50KGgpKWAgaXMgYGhgIGZvciBhbnkgdmFsaWQgdmVyc2lvbi0wMCBgaGAuXG4gKlxuICogQGV4YW1wbGVcbiAqIGZvcm1hdFRyYWNlcGFyZW50KHsgdHJhY2VJZCwgb3BlcmF0aW9uSWQ6IG15U3BhbklkLCBzYW1wbGVkOiB0cnVlIH0pOyAvLyAnMDAtPHRyYWNlSWQ+LTxteVNwYW5JZD4tMDEnXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBmb3JtYXRUcmFjZXBhcmVudChmaWVsZHM6IFRyYWNlcGFyZW50RmllbGRzKTogc3RyaW5nIHtcbiAgY29uc3QgeyB0cmFjZUlkLCBvcGVyYXRpb25JZCB9ID0gZmllbGRzO1xuICBpZiAodHlwZW9mIHRyYWNlSWQgIT09ICdzdHJpbmcnIHx8IHR5cGVvZiBvcGVyYXRpb25JZCAhPT0gJ3N0cmluZycpIHRocm93IG5ldyBUcmFjZXBhcmVudEVycm9yKCdub3QtYS1zdHJpbmcnKTtcbiAgaWYgKCFIRVgzMi50ZXN0KHRyYWNlSWQpIHx8ICFIRVgxNi50ZXN0KG9wZXJhdGlvbklkKSkgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ2NoYXJhY3RlcnMnKTtcbiAgaWYgKFpFUk9TLnRlc3QodHJhY2VJZCkpIHRocm93IG5ldyBUcmFjZXBhcmVudEVycm9yKCd6ZXJvLXRyYWNlLWlkJyk7XG4gIGlmIChaRVJPUy50ZXN0KG9wZXJhdGlvbklkKSkgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ3plcm8tcGFyZW50LWlkJyk7XG4gIHJldHVybiBgMDAtJHt0cmFjZUlkfS0ke29wZXJhdGlvbklkfS0ke2ZsYWdzT2YoZmllbGRzKX1gO1xufVxuXG4vKiogVGhlIHRyYWNlLWZsYWdzIGJ5dGUgdG8gd3JpdGU6IHRoZSBnaXZlbiBvbmUgKG9yIGAwMGApLCBiaXQgMCBzZXQgb3IgY2xlYXJlZCBieSBgc2FtcGxlZGAgd2hlbiBpdCBpcyBnaXZlbi4gKi9cbmZ1bmN0aW9uIGZsYWdzT2YoZmllbGRzOiBUcmFjZXBhcmVudEZpZWxkcyk6IHN0cmluZyB7XG4gIGNvbnN0IHsgZmxhZ3MgPSAnMDAnLCBzYW1wbGVkIH0gPSBmaWVsZHM7XG4gIGlmICh0eXBlb2YgZmxhZ3MgIT09ICdzdHJpbmcnKSB0aHJvdyBuZXcgVHJhY2VwYXJlbnRFcnJvcignbm90LWEtc3RyaW5nJyk7XG4gIGlmICghSEVYMi50ZXN0KGZsYWdzKSkgdGhyb3cgbmV3IFRyYWNlcGFyZW50RXJyb3IoJ2NoYXJhY3RlcnMnKTtcbiAgaWYgKHNhbXBsZWQgPT09IHVuZGVmaW5lZCkgcmV0dXJuIGZsYWdzO1xuICBjb25zdCBieXRlID0gc2FtcGxlZCA/IHBhcnNlSW50KGZsYWdzLCAxNikgfCAxIDogcGFyc2VJbnQoZmxhZ3MsIDE2KSAmIDB4ZmU7XG4gIHJldHVybiBieXRlLnRvU3RyaW5nKDE2KS5wYWRTdGFydCgyLCAnMCcpO1xufVxuXG4vKiogVGhlIGVudiBmaWVsZHMgY29ycmVsYXRpb24gcmVhZHMg4oCUIHN0cnVjdHVyYWwsIHNvIHRoaXMgTDUgZmlsZSBuYW1lcyBub3RoaW5nIG9mIHRoZSBlbmdpbmUncyBgRXhlY3V0aW9uRW52YC4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQ29ycmVsYXRpb25FbnYge1xuICByZWFkb25seSB0cmFjZXBhcmVudD86IHVua25vd247XG4gIHJlYWRvbmx5IHRyYWNlSWQ/OiB1bmtub3duO1xuICByZWFkb25seSBvcGVyYXRpb25JZD86IHVua25vd247XG59XG5cbi8qKiBBbiBleHBsaWNpdCBpZDogMeKAkzI1NiBwcmludGFibGUgQVNDSUkgY2hhcmFjdGVycywgbm8gc3BhY2Ug4oCUIGEgbmFtZSBhIGxvZyBsaW5lIG9yIGFuIGV4cG9ydGVyIGNhbiBjYXJyeS4gKi9cbmNvbnN0IEVYUExJQ0lUX0lEID0gL15bXFx4MjEtXFx4N2VdezEsMjU2fSQvO1xuXG4vKipcbiAqIEFkbWl0IGEgbGVnJ3MgZW52IE9OQ0UgKGNhbGxlZCBieSBgRmxvd0NoYXJ0RXhlY3V0b3IgwrcgcnVuYCAvIGByZXN1bWVgIGJlZm9yZSBhbnl0aGluZyBtb3Zlcyk6IGEgc2luZ2xlXG4gKiBvd24tcHJvcGVydHkgc25hcHNob3Qgb2YgaXQg4oCUIGV2ZXJ5IGdldHRlciBydW5zIG9uY2UsIG5vdGhpbmcgaXMgcmVhZCBvZmYgdGhlIHByb3RvdHlwZSDigJQgYW5kIHRoZSBjb3JyZWxhdGlvblxuICogcmVzb2x2ZWQgZnJvbSB0aGF0IHNuYXBzaG90LiBJbiB0aGUgc25hcHNob3QgdGhlIHN0YWdlcyBzZWUgKGAkZ2V0RW52KClgKSwgYHRyYWNlcGFyZW50YCBpcyBleGFjdGx5XG4gKiBgY29ycmVsYXRpb24udHJhY2VwYXJlbnRgIOKAlCB0aGUgY2Fub25pY2FsIGhlYWRlciBvZiB0aGUgZWZmZWN0aXZlIGlkcywgb3Igbm8ga2V5IHdoZW4gdGhlIHJ1bidzIGNvcnJlbGF0aW9uIGhhc1xuICogbm9uZSDigJQgc28gc3RhZ2UgY29kZSBuZXZlciBob2xkcyB0aGUgcmVjZWl2ZWQgYnl0ZXMsIG5vciBhIGhlYWRlciBuYW1pbmcgYW5vdGhlciB0cmFjZSB0aGFuIHRoZSByZWNvcmQuXG4gKiBgZW52YCBpcyBgdW5kZWZpbmVkYCBleGFjdGx5IHdoZW4gbm9uZSB3YXMgZ2l2ZW4uXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBhZG1pdFJ1bkVudjxFIGV4dGVuZHMgb2JqZWN0PihcbiAgZW52OiBFIHwgdW5kZWZpbmVkLFxuKTogeyByZWFkb25seSBlbnY6IEUgfCB1bmRlZmluZWQ7IHJlYWRvbmx5IGNvcnJlbGF0aW9uOiBSdW5Db3JyZWxhdGlvbiB8IHVuZGVmaW5lZCB9IHtcbiAgaWYgKGVudiA9PT0gdW5kZWZpbmVkIHx8IGVudiA9PT0gbnVsbCkgcmV0dXJuIHsgZW52OiB1bmRlZmluZWQsIGNvcnJlbGF0aW9uOiB1bmRlZmluZWQgfTtcbiAgY29uc3Qgc25hcHNob3QgPSB7IC4uLmVudiB9IGFzIEUgJiB7IHRyYWNlcGFyZW50PzogdW5rbm93biB9O1xuICBjb25zdCBjb3JyZWxhdGlvbiA9IHJlc29sdmVQYXJzZWQoc25hcHNob3QpO1xuICBpZiAoY29ycmVsYXRpb24/LnRyYWNlcGFyZW50ICE9PSB1bmRlZmluZWQpIHNuYXBzaG90LnRyYWNlcGFyZW50ID0gY29ycmVsYXRpb24udHJhY2VwYXJlbnQ7XG4gIGVsc2UgaWYgKHNuYXBzaG90LnRyYWNlcGFyZW50ICE9PSB1bmRlZmluZWQpIGRlbGV0ZSBzbmFwc2hvdC50cmFjZXBhcmVudDsgLy8gYSBoZWFkZXIgdGhlIHJlY29yZCBkb2VzIG5vdCBjYXJyeVxuICByZXR1cm4geyBlbnY6IHNuYXBzaG90LCBjb3JyZWxhdGlvbiB9O1xufVxuXG4vKipcbiAqIFRoZSBPTkUgcmVzb2x1dGlvbiBvZiBhIGxlZydzIGNvcnJlbGF0aW9uIGZyb20gaXRzIGVudi4gT25seSBPV04gZmllbGRzIGNvdW50LiBgdHJhY2VwYXJlbnRgIGlzIHBhcnNlZCBvbmNlIChhXG4gKiBiYWQgaGVhZGVyIHJlZnVzZXMgdGhlIGxlZyDigJQgZXhwbGljaXQgaWRzIGRvIG5vdCByZXNjdWUgaXQpOyBleHBsaWNpdCBgdHJhY2VJZGAgLyBgb3BlcmF0aW9uSWRgIHdpbiBvdmVyIHRoZVxuICogaGVhZGVyJ3MgYW5kIG11c3QgYmUgMeKAkzI1NiBwcmludGFibGUgQVNDSUkgY2hhcmFjdGVycyAocmVmdXNlZCBieSBmaWVsZCBuYW1lLCBuZXZlciBlY2hvZWQpOyBhbiBlbXB0eSBvbmUgaXNcbiAqIG5vIGlkLiBFdmVyeXRoaW5nIG9mIHRoZSBoZWFkZXIg4oCUIGl0cyBwYXJlbnQtaWQgYXMgdGhlIG9wZXJhdGlvbiwgYHNhbXBsZWRgLCBgdHJhY2VwYXJlbnRgIOKAlCByaWRlcyBvbmx5IHdoaWxlXG4gKiB0aGUgdHJhY2UgSVMgdGhlIGhlYWRlcidzLCBhbmQgYHRyYWNlcGFyZW50YCBpcyByZWJ1aWx0IGZyb20gdGhlIEVGRkVDVElWRSBpZHMgd2l0aCB0aGUgaGVhZGVyJ3MgZmxhZ3NcbiAqIChvbWl0dGVkIHdoZW4gdGhlIG9wZXJhdGlvbiBpcyBub3QgYSBXM0MgcGFyZW50LWlkKSwgc28gdGhlIHJlY29yZCBuZXZlciBuYW1lcyBvbmUgdHJhY2UgYW5kIGZpbGVzIG9yXG4gKiBwcm9wYWdhdGVzIGFub3RoZXIncy4gUmV0dXJucyBgdW5kZWZpbmVkYCB3aGVuIHRoZXJlIGlzIG5vIHRyYWNlIGlkIGF0IGFsbCDigJQgYW5kIHJlZnVzZXNcbiAqIGFuIGBvcGVyYXRpb25JZGAgd2l0aCBubyB0cmFjZSB0byBiZWxvbmcgdG8uXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXNvbHZlQ29ycmVsYXRpb24oZW52OiBDb3JyZWxhdGlvbkVudiB8IHVuZGVmaW5lZCk6IFJ1bkNvcnJlbGF0aW9uIHwgdW5kZWZpbmVkIHtcbiAgaWYgKGVudiA9PT0gdW5kZWZpbmVkIHx8IGVudiA9PT0gbnVsbCkgcmV0dXJuIHVuZGVmaW5lZDtcbiAgcmV0dXJuIHJlc29sdmVQYXJzZWQoeyAuLi5lbnYgfSk7XG59XG5cbi8qKiB7QGxpbmsgcmVzb2x2ZUNvcnJlbGF0aW9ufSBvdmVyIGFuIGVudiBhbHJlYWR5IHNuYXBzaG90dGVkIChlYWNoIGZpZWxkIHJlYWQgb25jZSkuICovXG5mdW5jdGlvbiByZXNvbHZlUGFyc2VkKGVudjogQ29ycmVsYXRpb25FbnYpOiBSdW5Db3JyZWxhdGlvbiB8IHVuZGVmaW5lZCB7XG4gIGNvbnN0IHJhdyA9IG93bihlbnYsICd0cmFjZXBhcmVudCcpO1xuICBjb25zdCBoZWFkZXIgPSByYXcgPT09IHVuZGVmaW5lZCA/IHVuZGVmaW5lZCA6IHBhcnNlVHJhY2VwYXJlbnQocmF3KTtcbiAgY29uc3QgdHJhY2VJZCA9IGV4cGxpY2l0SWQob3duKGVudiwgJ3RyYWNlSWQnKSwgJ3RyYWNlSWQnKSA/PyBoZWFkZXI/LnRyYWNlSWQ7XG4gIGNvbnN0IHNhbWVUcmFjZSA9IGhlYWRlciAhPT0gdW5kZWZpbmVkICYmIHRyYWNlSWQgPT09IGhlYWRlci50cmFjZUlkO1xuICBjb25zdCBvcGVyYXRpb25JZCA9XG4gICAgZXhwbGljaXRJZChvd24oZW52LCAnb3BlcmF0aW9uSWQnKSwgJ29wZXJhdGlvbklkJykgPz8gKHNhbWVUcmFjZSA/IGhlYWRlci5vcGVyYXRpb25JZCA6IHVuZGVmaW5lZCk7XG4gIGlmICh0cmFjZUlkID09PSB1bmRlZmluZWQpIHtcbiAgICBpZiAob3BlcmF0aW9uSWQgIT09IHVuZGVmaW5lZCkge1xuICAgICAgdGhyb3cgbmV3IFR5cGVFcnJvcignZW52Lm9wZXJhdGlvbklkIG5lZWRzIGEgdHJhY2UgdG8gYmVsb25nIHRvOiBnaXZlIGVudi50cmFjZUlkIG9yIGVudi50cmFjZXBhcmVudCcpO1xuICAgIH1cbiAgICByZXR1cm4gdW5kZWZpbmVkO1xuICB9XG4gIGNvbnN0IHByb3BhZ2FibGUgPSBzYW1lVHJhY2UgJiYgb3BlcmF0aW9uSWQgIT09IHVuZGVmaW5lZCAmJiBIRVgxNi50ZXN0KG9wZXJhdGlvbklkKSAmJiAhWkVST1MudGVzdChvcGVyYXRpb25JZCk7XG4gIHJldHVybiBPYmplY3QuZnJlZXplKHtcbiAgICB0cmFjZUlkLFxuICAgIC4uLihvcGVyYXRpb25JZCAhPT0gdW5kZWZpbmVkICYmIHsgb3BlcmF0aW9uSWQgfSksXG4gICAgLi4uKHNhbWVUcmFjZSAmJiB7IHNhbXBsZWQ6IGhlYWRlci5zYW1wbGVkIH0pLFxuICAgIC4uLihwcm9wYWdhYmxlICYmIHsgdHJhY2VwYXJlbnQ6IGZvcm1hdFRyYWNlcGFyZW50KHsgdHJhY2VJZCwgb3BlcmF0aW9uSWQsIGZsYWdzOiBoZWFkZXIuZmxhZ3MgfSkgfSksXG4gIH0pO1xufVxuXG4vKiogQW4gb3duIGZpZWxkJ3MgdmFsdWUg4oCUIGEgdmFsdWUgaW5oZXJpdGVkIHRocm91Z2ggdGhlIHByb3RvdHlwZSBpcyBub3QgdGhlIGNhbGxlcidzLiAqL1xuZnVuY3Rpb24gb3duKGVudjogQ29ycmVsYXRpb25FbnYsIGZpZWxkOiBrZXlvZiBDb3JyZWxhdGlvbkVudik6IHVua25vd24ge1xuICByZXR1cm4gT2JqZWN0LnByb3RvdHlwZS5oYXNPd25Qcm9wZXJ0eS5jYWxsKGVudiwgZmllbGQpID8gZW52W2ZpZWxkXSA6IHVuZGVmaW5lZDtcbn1cblxuZnVuY3Rpb24gZXhwbGljaXRJZCh2YWx1ZTogdW5rbm93biwgZmllbGQ6ICd0cmFjZUlkJyB8ICdvcGVyYXRpb25JZCcpOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICBpZiAodmFsdWUgPT09IHVuZGVmaW5lZCB8fCB2YWx1ZSA9PT0gJycpIHJldHVybiB1bmRlZmluZWQ7XG4gIGlmICh0eXBlb2YgdmFsdWUgIT09ICdzdHJpbmcnKSB0aHJvdyBuZXcgVHlwZUVycm9yKGBlbnYuJHtmaWVsZH0gbXVzdCBiZSBhIHN0cmluZ2ApO1xuICBpZiAoIUVYUExJQ0lUX0lELnRlc3QodmFsdWUpKSB7XG4gICAgdGhyb3cgbmV3IFR5cGVFcnJvcihgZW52LiR7ZmllbGR9IHJlZnVzZWQ6IGFuIGlkIGlzIDHigJMyNTYgcHJpbnRhYmxlIEFTQ0lJIGNoYXJhY3RlcnMgd2l0aCBubyBzcGFjZWApO1xuICB9XG4gIHJldHVybiB2YWx1ZTtcbn1cbiJdfQ==

package/dist/esm/lib/attempt/deadline.d.ts

@@ -0,0 +1,44 @@
+/**
+ * attempt/deadline.ts — what the run's deadline IS, to everything that reads time (design §3.1, law 3).
+ *
+ * The deadline is one number, epoch milliseconds (`env.deadline`); the executor arms the run's signal to abort when
+ * it passes (`runner/deadline.ts · armRun`). Reaching it is NOT a cancellation: an attempt the deadline cuts short
+ * timed out (it had no answer in the time it had — law 4), and the series stops `no-time-left`, not `aborted`. So
+ * the reason the run's signal aborts with at the deadline is BRANDED here, and the attempt runner tells the two
+ * apart by the brand — never by the message, never by the clock.
+ *
+ * The brand is a module-private WeakSet: an ordinary `Error` (same message, same name a run with `timeoutMs` always
+ * rejected with), recognisable only by identity.
+ */
+/** The reason the run's signal aborts with when its deadline passes — an `Error`, branded as the deadline's. */
+export declare function deadlineReason(message: string): Error;
+/**
+ * Brand `reason` as a time limit — what an attempt's own cap aborts with (P2). An attempt's cap is the deadline of
+ * every call made inside it (`attempt/call.ts`), so a call it cuts ran out of time: `'timeout'`, never `'aborted'`.
+ * The run's own signal never aborts with it, so a stage attempt reads nothing new.
+ */
+export declare function markTimeLimit<T extends object>(reason: T): T;
+/** Whether `reason` is the run's deadline or an attempt's cap — a time limit, not a cancellation. */
+export declare function isDeadlineReason(reason: unknown): boolean;
+/** Whether the signal aborted for a reason OTHER than a time limit — a cancellation. */
+export declare function isCancelled(signal: AbortSignal | undefined): boolean;
+/** A deadline as the engine reads one: a finite number (epoch ms), else none. */
+export declare function readDeadline(value: unknown): number | undefined;
+/**
+ * `setTimeout` for any delay: a delay past the host's limit is waited in chunks, so a 30-day deadline does not fire
+ * in a millisecond. Returns the one call that cancels it.
+ */
+export declare function setLongTimeout(fn: () => void, ms: number): () => void;
+/** Whether `value` is an AbortSignal (structurally — a signal from another realm counts). */
+export declare function isAbortSignal(value: unknown): value is AbortSignal;
+/** A signal that aborts at a deadline (or with its input), and the one call that releases both. */
+export interface ArmedDeadline {
+    readonly signal: AbortSignal | undefined;
+    dispose(): void;
+}
+/**
+ * Compose `signal` with a timer that aborts at `deadline` (epoch ms) with a branded {@link deadlineReason} — so the
+ * attempt runner's reading holds: the signal it is handed aborts at the deadline, as the run's does (`armRun`). A
+ * deadline already past aborts at once; without a deadline the signal is handed back as it is.
+ */
+export declare function armDeadline(signal: AbortSignal | undefined, deadline: number | undefined, message: string, now?: () => number): ArmedDeadline;