@nifrajs/core 1.9.1 → 1.11.0

package/dist/capabilities.js

@@ -0,0 +1,283 @@
+/**
+ * Route effect/capability assurance. Declarations are reflected at build/CI time; runtime beacons
+ * are a fail-closed defence at owned effect seams. Static provenance remains the security anchor.
+ */
+import { CAPABILITY_GUARD, validCapabilityId, } from "./internal/capability-runtime.js";
+import { NIFRA_ASSURANCE_IDS } from "./internal/route-assurance.js";
+import { effectLedgerOf } from "./ledger.js";
+import { reflectRoutes } from "./reflection.js";
+const SAFE_METHODS = new Set(["GET", "HEAD"]);
+export { validCapabilityId };
+function normalizedIds(values, label) {
+    if (!Array.isArray(values))
+        throw new TypeError(`${label} must be an array`);
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== "string" || !validCapabilityId(value)) {
+            throw new Error(`capability assurance: invalid ${label} id ${JSON.stringify(value)}`);
+        }
+        if (!seen.has(value)) {
+            seen.add(value);
+            out.push(value);
+        }
+    }
+    return Object.freeze(out);
+}
+function validSpecifier(value) {
+    return value.trim() === value && value !== "" && !hasControlCharacter(value);
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+/** Validate and freeze a capability/provenance policy. */
+export function defineCapabilityPolicy(policy) {
+    if (policy.provenance === undefined || policy.provenance === null) {
+        throw new Error("capability assurance: provenance policy is required");
+    }
+    const ids = new Set();
+    const definitions = policy.definitions.map((definition) => {
+        if (!validCapabilityId(definition.id)) {
+            throw new Error(`capability assurance: invalid capability id ${JSON.stringify(definition.id)}`);
+        }
+        if (ids.has(definition.id)) {
+            throw new Error(`capability assurance: duplicate capability ${JSON.stringify(definition.id)}`);
+        }
+        ids.add(definition.id);
+        if (definition.zone !== "domain" && definition.zone !== "operational") {
+            throw new Error(`capability assurance: invalid zone for ${definition.id}`);
+        }
+        if (definition.access !== "read" && definition.access !== "write") {
+            throw new Error(`capability assurance: invalid access for ${definition.id}`);
+        }
+        const idempotency = definition.idempotency ?? "none";
+        if (idempotency !== "none" && idempotency !== "request" && idempotency !== "durable") {
+            throw new Error(`capability assurance: invalid idempotency for ${definition.id}`);
+        }
+        if (definition.access === "read" && idempotency !== "none") {
+            throw new Error(`capability assurance: read capability ${definition.id} cannot require idempotency`);
+        }
+        return Object.freeze({ ...definition, idempotency });
+    });
+    const imports = policy.provenance.imports.map((rule) => {
+        if (!validSpecifier(rule.specifier))
+            throw new Error("capability assurance: invalid import specifier");
+        const capabilities = normalizedIds(rule.capabilities, "import capability");
+        for (const id of capabilities) {
+            if (!ids.has(id))
+                throw new Error(`capability assurance: import references unknown ${id}`);
+        }
+        return Object.freeze({ specifier: rule.specifier, capabilities });
+    });
+    const forbiddenImports = policy.provenance.forbiddenImports.map((rule) => {
+        if (!validSpecifier(rule.specifier) || rule.reason.trim() === "") {
+            throw new Error("capability assurance: forbidden import needs a specifier and reason");
+        }
+        return Object.freeze({ specifier: rule.specifier, reason: rule.reason.trim() });
+    });
+    const routeModules = policy.provenance.routeModules?.map((rule) => {
+        if (!Array.isArray(rule.modules) || rule.modules.length === 0) {
+            throw new Error("capability assurance: routeModules entry needs at least one module");
+        }
+        const modules = rule.modules.map((module) => {
+            if (!validSpecifier(module))
+                throw new Error("capability assurance: invalid route module");
+            return module.replace(/^\.\//, "");
+        });
+        return Object.freeze({
+            match: Object.freeze({
+                ...(rule.match.methods !== undefined
+                    ? { methods: Object.freeze(rule.match.methods.map((method) => method.toUpperCase())) }
+                    : {}),
+                ...(rule.match.paths !== undefined ? { paths: Object.freeze([...rule.match.paths]) } : {}),
+            }),
+            modules: Object.freeze(modules),
+        });
+    });
+    return Object.freeze({
+        definitions: Object.freeze(definitions),
+        provenance: Object.freeze({
+            imports: Object.freeze(imports),
+            forbiddenImports: Object.freeze(forbiddenImports),
+            ...(routeModules !== undefined ? { routeModules: Object.freeze(routeModules) } : {}),
+        }),
+        lockfile: policy.lockfile ?? "capabilities.lock.json",
+    });
+}
+function evidenceSourceValid(source) {
+    return source.length > 0 && source.length <= 256 && !hasControlCharacter(source);
+}
+function routeKey(method, path) {
+    return `${method.toUpperCase()}\n${path}`;
+}
+/** Compare declared route capabilities against coverage-qualified static/runtime evidence. */
+export function evaluateCapabilityAssurance(source, policyInput, evidenceSet) {
+    const policy = defineCapabilityPolicy(policyInput);
+    const definitions = new Map(policy.definitions.map((definition) => [definition.id, definition]));
+    const evidenceByRoute = new Map(evidenceSet.routes.map((route) => [routeKey(route.method, route.path), route]));
+    const findings = [];
+    const routes = [];
+    for (const route of reflectRoutes(source)) {
+        const declared = route.capabilities ?? [];
+        const supplied = evidenceByRoute.get(routeKey(route.method, route.path));
+        const covered = supplied?.covered === true;
+        const evidence = [];
+        const evidenceIds = new Set();
+        for (const item of supplied?.evidence ?? []) {
+            if (!validCapabilityId(item.id) ||
+                (item.kind !== "static" && item.kind !== "runtime") ||
+                !evidenceSourceValid(item.source)) {
+                continue;
+            }
+            const key = `${item.id}\n${item.kind}\n${item.source}`;
+            if (evidence.some((candidate) => `${candidate.id}\n${candidate.kind}\n${candidate.source}` === key))
+                continue;
+            evidence.push(Object.freeze({ id: item.id, kind: item.kind, source: item.source }));
+            evidenceIds.add(item.id);
+        }
+        for (const id of declared) {
+            if (!definitions.has(id)) {
+                findings.push({
+                    code: "unknown-capability",
+                    method: route.method,
+                    path: route.path,
+                    capability: id,
+                    message: `${route.method} ${route.path} declares unknown capability ${id}`,
+                });
+            }
+        }
+        if (!covered) {
+            findings.push({
+                code: "provenance-uncovered",
+                method: route.method,
+                path: route.path,
+                message: `${route.method} ${route.path} has no static provenance coverage`,
+            });
+        }
+        for (const id of evidenceIds) {
+            if (!declared.includes(id)) {
+                findings.push({
+                    code: "undeclared-capability-evidence",
+                    method: route.method,
+                    path: route.path,
+                    capability: id,
+                    message: `${route.method} ${route.path} evidence exceeds its declaration: ${id}`,
+                });
+            }
+        }
+        const effective = new Set([...declared, ...evidenceIds]);
+        const assuranceIds = new Set((route.assurance ?? []).map((item) => item.id));
+        for (const id of effective) {
+            const definition = definitions.get(id);
+            if (definition === undefined)
+                continue;
+            if (SAFE_METHODS.has(route.method) &&
+                definition.zone === "domain" &&
+                definition.access === "write") {
+                findings.push({
+                    code: "safe-method-domain-write",
+                    method: route.method,
+                    path: route.path,
+                    capability: id,
+                    message: `${route.method} ${route.path} cannot carry domain write capability ${id}`,
+                });
+            }
+            if (definition.idempotency === "request" &&
+                !assuranceIds.has(NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY)) {
+                findings.push({
+                    code: "missing-request-idempotency",
+                    method: route.method,
+                    path: route.path,
+                    capability: id,
+                    message: `${route.method} ${route.path} capability ${id} requires request idempotency evidence`,
+                });
+            }
+            if (definition.idempotency === "durable" &&
+                !assuranceIds.has(NIFRA_ASSURANCE_IDS.DURABLE_COMMAND)) {
+                findings.push({
+                    code: "missing-durable-idempotency",
+                    method: route.method,
+                    path: route.path,
+                    capability: id,
+                    message: `${route.method} ${route.path} capability ${id} requires durable command/provider-key evidence`,
+                });
+            }
+        }
+        routes.push(Object.freeze({
+            method: route.method,
+            path: route.path,
+            declared: Object.freeze([...declared]),
+            evidence: Object.freeze(evidence),
+            unproven: Object.freeze(declared.filter((id) => !evidenceIds.has(id))),
+            covered,
+            ...(route.classification !== undefined ? { classification: route.classification.max } : {}),
+        }));
+    }
+    return Object.freeze({
+        ok: findings.length === 0,
+        routes: Object.freeze(routes),
+        findings: Object.freeze(findings),
+    });
+}
+function guardFor(context, capability) {
+    if (!validCapabilityId(capability)) {
+        throw new Error(`capability assurance: invalid runtime capability ${JSON.stringify(capability)}`);
+    }
+    const guard = context[CAPABILITY_GUARD];
+    if (guard === undefined) {
+        throw new Error(`capability assurance: ${capability} used on a route with no capability declaration`);
+    }
+    if (!guard.allowed.includes(capability)) {
+        throw new Error(`capability assurance: ${capability} is not declared for ${guard.method} ${guard.path}`);
+    }
+    return guard;
+}
+/**
+ * Runtime effect beacon for owned adapters. It fails closed when the route omitted the capability or
+ * when no route guard is present. Static provenance is still required: code can bypass a beacon.
+ * When the server enabled the effect ledger, each beacon call also appends one token-only entry.
+ */
+export function useCapability(context, capability, options) {
+    const guard = guardFor(context, capability);
+    const ledger = effectLedgerOf(context);
+    // Validate/append the intent before private admission hooks debit budgets. Overflow or malformed
+    // evidence therefore cannot consume quota and then fail the request.
+    ledger?.append({ capability, ...options, phase: "intent" });
+    guard.onUse?.({ capability, method: guard.method, path: guard.path });
+}
+/** Record the terminal outcome of an already-admitted capability without debiting admission twice. */
+export function recordCapabilityOutcome(context, capability, options) {
+    guardFor(context, capability);
+    const ledger = effectLedgerOf(context);
+    if (ledger === undefined)
+        return;
+    ledger.append({ capability, ...options });
+}
+/**
+ * Read the route's token-only declaration for admission plugins. This intentionally exposes neither
+ * the request nor runtime evidence; it is the stable public seam for private entitlement policy.
+ */
+export function declaredCapabilities(context) {
+    const guard = context[CAPABILITY_GUARD];
+    return guard?.allowed ?? Object.freeze([]);
+}
+/** Deterministic, PII-free lockfile material. */
+export function snapshotCapabilities(report) {
+    const routes = report.routes
+        .map((route) => ({
+        method: route.method,
+        path: route.path,
+        declared: Object.freeze([...route.declared].sort()),
+        evidenced: Object.freeze([...new Set(route.evidence.map((item) => item.id))].sort()),
+        unproven: Object.freeze([...route.unproven].sort()),
+        ...(route.classification !== undefined ? { classification: route.classification } : {}),
+    }))
+        .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+    return Object.freeze({ nifraCapabilities: 1, routes: Object.freeze(routes) });
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

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

package/dist/classification.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Response data-classification tags. A route can declare the highest sensitivity its response body
+ * carries (`schema.classification`). This is a declarative, compile-time + introspection fact — never
+ * read on the request hot path and never enforced at runtime here. Downstream consumers use it: a
+ * partner-API surface refuses to expose a route whose response is `pii`/`secret`, privacy tooling
+ * learns which routes emit regulated data, and the capability lockfile records it so a route that
+ * *starts* returning PII flips the lockfile and forces a review.
+ */
+/** Sensitivity of the data a response carries. Ordered `public` < `pii` < `secret`. */
+export type DataClassification = "public" | "pii" | "secret";
+/** Field paths use JSON Pointer segments; array items use a `*` segment. */
+export interface ResponseClassification {
+    readonly fields: Readonly<Record<string, DataClassification>>;
+    readonly max: DataClassification;
+}
+declare const CLASSIFICATION: unique symbol;
+export type ClassifiedSchema<S extends object> = S & {
+    readonly [CLASSIFICATION]: DataClassification;
+};
+/** Total order over classifications; higher = more sensitive. */
+export declare const DATA_CLASSIFICATION_RANK: Readonly<Record<DataClassification, number>>;
+/** Whether `value` is a known classification token. */
+export declare function isDataClassification(value: unknown): value is DataClassification;
+/** The most sensitive classification among the inputs; `"public"` when none are given. */
+export declare function maxClassification(values: Iterable<DataClassification>): DataClassification;
+/** True when `value` is at least as sensitive as `floor` (e.g. `classificationAtLeast(x, "pii")`). */
+export declare function classificationAtLeast(value: DataClassification, floor: DataClassification): boolean;
+/**
+ * Attach data-classification metadata without changing validation or inferred input/output types.
+ * For Nifra/TypeBox carriers the raw JSON Schema node is tagged too, so metadata survives composition
+ * through `t.object`, `t.array`, `t.optional`, and unions.
+ */
+export declare function classified<S extends object>(schema: S, classification: DataClassification): ClassifiedSchema<S>;
+/** Read field-level metadata from an introspectable response schema. Never invokes its validator. */
+export declare function reflectClassification(schema: unknown): ResponseClassification | undefined;
+/** Merge field metadata with an optional route-level sensitivity fallback. */
+export declare function routeClassification(responseSchema: unknown, fallback: DataClassification | undefined): ResponseClassification | undefined;
+export {};
+//# sourceMappingURL=classification.d.ts.map

package/dist/classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.d.ts","sourceRoot":"","sources":["../src/classification.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAA;AAE5D,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAA;IAC7D,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAA;CACjC;AAED,QAAA,MAAM,cAAc,eAA0C,CAAA;AAQ9D,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IACnD,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAA;CAC9C,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAMjF,CAAA;AAID,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEhF;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAM1F;AAED,sGAAsG;AACtG,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAET;AAuBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,MAAM,EAAE,CAAC,EACT,cAAc,EAAE,kBAAkB,GACjC,gBAAgB,CAAC,CAAC,CAAC,CAerB;AAiBD,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,sBAAsB,GAAG,SAAS,CA+CzF;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,OAAO,EACvB,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACvC,sBAAsB,GAAG,SAAS,CAUpC"}

package/dist/classification.js

@@ -0,0 +1,153 @@
+/**
+ * Response data-classification tags. A route can declare the highest sensitivity its response body
+ * carries (`schema.classification`). This is a declarative, compile-time + introspection fact — never
+ * read on the request hot path and never enforced at runtime here. Downstream consumers use it: a
+ * partner-API surface refuses to expose a route whose response is `pii`/`secret`, privacy tooling
+ * learns which routes emit regulated data, and the capability lockfile records it so a route that
+ * *starts* returning PII flips the lockfile and forces a review.
+ */
+const CLASSIFICATION = Symbol.for("nifra.data-classification");
+const JSON_SCHEMA_CLASSIFICATION = "x-nifra-classification";
+/** Total order over classifications; higher = more sensitive. */
+export const DATA_CLASSIFICATION_RANK = Object.freeze({
+    public: 0,
+    pii: 1,
+    secret: 2,
+});
+const CLASSIFICATIONS = Object.keys(DATA_CLASSIFICATION_RANK);
+/** Whether `value` is a known classification token. */
+export function isDataClassification(value) {
+    return typeof value === "string" && CLASSIFICATIONS.includes(value);
+}
+/** The most sensitive classification among the inputs; `"public"` when none are given. */
+export function maxClassification(values) {
+    let max = "public";
+    for (const value of values) {
+        if (DATA_CLASSIFICATION_RANK[value] > DATA_CLASSIFICATION_RANK[max])
+            max = value;
+    }
+    return max;
+}
+/** True when `value` is at least as sensitive as `floor` (e.g. `classificationAtLeast(x, "pii")`). */
+export function classificationAtLeast(value, floor) {
+    return DATA_CLASSIFICATION_RANK[value] >= DATA_CLASSIFICATION_RANK[floor];
+}
+function cloneObject(value) {
+    return Object.create(Object.getPrototypeOf(value), Object.getOwnPropertyDescriptors(value));
+}
+function tagObject(value, classification) {
+    const clone = cloneObject(value);
+    Object.defineProperty(clone, CLASSIFICATION, {
+        configurable: false,
+        enumerable: true,
+        value: classification,
+        writable: false,
+    });
+    Object.defineProperty(clone, JSON_SCHEMA_CLASSIFICATION, {
+        configurable: true,
+        enumerable: true,
+        value: classification,
+        writable: true,
+    });
+    return clone;
+}
+/**
+ * Attach data-classification metadata without changing validation or inferred input/output types.
+ * For Nifra/TypeBox carriers the raw JSON Schema node is tagged too, so metadata survives composition
+ * through `t.object`, `t.array`, `t.optional`, and unions.
+ */
+export function classified(schema, classification) {
+    if (!isDataClassification(classification)) {
+        throw new TypeError(`classification: invalid tag ${JSON.stringify(classification)}`);
+    }
+    const clone = tagObject(schema, classification);
+    const raw = schema.jsonSchema;
+    if (raw !== null && typeof raw === "object") {
+        Object.defineProperty(clone, "jsonSchema", {
+            configurable: true,
+            enumerable: true,
+            value: tagObject(raw, classification),
+            writable: false,
+        });
+    }
+    return clone;
+}
+const recordOf = (value) => value !== null && typeof value === "object"
+    ? value
+    : undefined;
+const classificationOf = (value) => {
+    const record = recordOf(value);
+    const symbolValue = value?.[CLASSIFICATION];
+    if (isDataClassification(symbolValue))
+        return symbolValue;
+    const extension = record?.[JSON_SCHEMA_CLASSIFICATION];
+    return isDataClassification(extension) ? extension : undefined;
+};
+const pointerSegment = (value) => value.replaceAll("~", "~0").replaceAll("/", "~1");
+/** Read field-level metadata from an introspectable response schema. Never invokes its validator. */
+export function reflectClassification(schema) {
+    const carrier = recordOf(schema);
+    const raw = carrier !== undefined && "jsonSchema" in carrier ? carrier.jsonSchema : schema;
+    const fields = {};
+    const seen = new Set();
+    const all = [];
+    const record = (path, value) => {
+        const key = path === "" ? "$" : path;
+        const previous = fields[key];
+        fields[key] = previous === undefined ? value : maxClassification([previous, value]);
+        all.push(value);
+    };
+    const visit = (value, path) => {
+        const object = recordOf(value);
+        if (object === undefined)
+            return;
+        if (seen.has(object))
+            return;
+        seen.add(object);
+        const own = classificationOf(value);
+        if (own !== undefined)
+            record(path, own);
+        const properties = recordOf(object.properties);
+        if (properties !== undefined) {
+            for (const [name, child] of Object.entries(properties)) {
+                visit(child, `${path}/${pointerSegment(name)}`);
+            }
+        }
+        if (object.items !== undefined)
+            visit(object.items, `${path}/*`);
+        if (Array.isArray(object.prefixItems)) {
+            for (const [index, child] of object.prefixItems.entries())
+                visit(child, `${path}/${index}`);
+        }
+        if (object.additionalProperties !== undefined && object.additionalProperties !== false) {
+            visit(object.additionalProperties, `${path}/*`);
+        }
+        for (const key of ["allOf", "anyOf", "oneOf"]) {
+            const variants = object[key];
+            if (Array.isArray(variants))
+                for (const child of variants)
+                    visit(child, path);
+        }
+    };
+    visit(raw, "");
+    // A validation-only carrier can still carry a root tag even when it has no JSON Schema metadata.
+    const carrierTag = classificationOf(schema);
+    if (carrierTag !== undefined && all.length === 0)
+        record("", carrierTag);
+    if (all.length === 0)
+        return undefined;
+    return Object.freeze({ fields: Object.freeze(fields), max: maxClassification(all) });
+}
+/** Merge field metadata with an optional route-level sensitivity fallback. */
+export function routeClassification(responseSchema, fallback) {
+    const reflected = reflectClassification(responseSchema);
+    if (reflected === undefined && fallback === undefined)
+        return undefined;
+    return Object.freeze({
+        fields: reflected?.fields ?? Object.freeze({}),
+        max: fallback === undefined
+            ? reflected.max
+            : maxClassification([fallback, ...(reflected === undefined ? [] : [reflected.max])]),
+    });
+}
+//# sourceMappingURL=classification.js.map

package/dist/classification.js.map

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

package/dist/errors.d.ts

@@ -8,7 +8,7 @@ export declare class FrameworkError extends Error {
     constructor(code: string, message: string);
 }
 /** Stable codes for boot-time (L2) route configuration failures. */
-export type RouteConfigErrorCode = "DUPLICATE_ROUTE" | "DUPLICATE_PARAM" | "PARAM_NAME_CONFLICT" | "INVALID_PATH" | "INVALID_PARAM_NAME" | "WILDCARD_NOT_LAST" | "INVALID_METHOD";
+export type RouteConfigErrorCode = "DUPLICATE_ROUTE" | "DUPLICATE_PARAM" | "PARAM_NAME_CONFLICT" | "INVALID_PATH" | "INVALID_PARAM_NAME" | "WILDCARD_NOT_LAST" | "INVALID_METHOD" | "INVALID_ASSURANCE" | "INVALID_IDEMPOTENCY";
 /**
  * Thrown at route registration when a route is misconfigured. This is the
  * boot-time rejection layer: loud and early,

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,GACrB,cAAc,GACd,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,CAAA;AAEpB;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,cAAc;IAElD,SAAiB,IAAI,EAAE,oBAAoB,CAAA;gBAE/B,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAIxD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,GACrB,cAAc,GACd,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,GAChB,mBAAmB,GACnB,qBAAqB,CAAA;AAEzB;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,cAAc;IAElD,SAAiB,IAAI,EAAE,oBAAoB,CAAA;gBAE/B,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAIxD"}

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAQ;IAErB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC,CAAA;QACvC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAYD;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAIlD,YAAY,IAA0B,EAAE,OAAe;QACrD,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAQ;IAErB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC,CAAA;QACvC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAcD;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAIlD,YAAY,IAA0B,EAAE,OAAe;QACrD,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF"}