@zenalexa/unicli 0.220.0 → 0.221.0

package/dist/engine/kernel/stages.js

@@ -0,0 +1,429 @@
+/**
+ * @owner Uni-CLI Kernel
+ * @does Implements explicit invocation stages shared by execute() and tests.
+ * @needs Invocation, compiled command cache, policy evaluator, pipeline runner.
+ * @feeds CLI/MCP/ACP kernel execution and stage parity tests.
+ * @breaks Any surface that bypasses compile, validate, harden, authorize, execute, observe, envelope, or repair diagnostics.
+ */
+import { PipelineError, runPipeline } from "../executor.js";
+import { hardenArgs, InputHardeningError } from "../harden.js";
+import { defaultSuccessNextActions, defaultErrorNextActions, } from "../../output/next-actions.js";
+import { buildBrowserCommandDiagnostic } from "../browser/diagnostics.js";
+import { createApprovalStore, rememberApproval } from "../approval-store.js";
+import { errorTypeToCode, errorToAgentFields, mapErrorToExitCode, } from "../../output/error-map.js";
+import { commandStrategy } from "../../registry.js";
+import { ExitCode } from "../../types.js";
+import { InvalidPermissionProfileError, resolveOperationAdapterPath, resolveOperationTargetSurface, } from "../operation-policy.js";
+import { evaluateOperationPolicyWithApprovals } from "../permission-runtime.js";
+import { PermissionRulesConfigError } from "../permission-rules.js";
+import { getCompiled } from "./compile.js";
+import { KernelLookupError } from "./errors.js";
+export const KERNEL_STAGE_ORDER = [
+    "compile",
+    "validate",
+    "harden",
+    "authorize",
+    "execute",
+    "observe",
+    "envelope",
+    "repair-diagnostics",
+];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function resourcesFromPermissionConfig(config) {
+    if (!isRecord(config) || !isRecord(config.resources))
+        return undefined;
+    const resources = {};
+    for (const [bucket, raw] of Object.entries(config.resources)) {
+        if (!Array.isArray(raw))
+            continue;
+        const values = raw.filter((value) => {
+            return typeof value === "string";
+        });
+        if (values.length > 0)
+            resources[bucket] = values;
+    }
+    return Object.keys(resources).length > 0 ? resources : undefined;
+}
+function runtimePermissionDeniedDiagnostic(err) {
+    if (!(err instanceof PipelineError) ||
+        err.detail.errorType !== "permission_denied") {
+        return undefined;
+    }
+    const config = err.detail.config;
+    const resources = resourcesFromPermissionConfig(config);
+    const ruleId = isRecord(config) && typeof config.rule_id === "string"
+        ? config.rule_id
+        : undefined;
+    return {
+        kind: "runtime_permission_denied",
+        code: "permission_denied",
+        action: err.detail.action,
+        step: err.detail.step,
+        retryable: err.detail.retryable ?? false,
+        ...(ruleId ? { rule_id: ruleId } : {}),
+        resource_buckets: resources ? Object.keys(resources).sort() : [],
+        ...(resources ? { resources } : {}),
+    };
+}
+export function diagnosticsForError(err) {
+    const diagnostic = runtimePermissionDeniedDiagnostic(err);
+    return diagnostic ? [diagnostic] : undefined;
+}
+function browserDiagnostics(inv, ctx) {
+    const diagnostic = buildBrowserCommandDiagnostic({
+        site: inv.adapter.name,
+        command: inv.cmdName,
+        adapterPath: ctx.adapterPath,
+        targetSurface: ctx.targetSurface,
+        browser: inv.adapter.browser === true || inv.command.browser === true,
+        domain: inv.command.domain ?? inv.adapter.domain,
+    });
+    return diagnostic ? [diagnostic] : undefined;
+}
+export function resolveKernelCommandContext(inv) {
+    const key = `${inv.adapter.name}.${inv.cmdName}`;
+    const compiled = getCompiled(inv.adapter.name, inv.cmdName);
+    if (!compiled)
+        throw new KernelLookupError(key);
+    const strategy = commandStrategy(inv.adapter, inv.command);
+    const targetSurface = resolveOperationTargetSurface({
+        adapterType: inv.adapter.type,
+        targetSurface: inv.command.target_surface,
+    });
+    const adapterPath = resolveOperationAdapterPath(inv.adapter.name, inv.cmdName, inv.command.adapter_path);
+    return { key, compiled, strategy, targetSurface, adapterPath };
+}
+function errorResult(input) {
+    const durationMs = Date.now() - input.startedAt;
+    return {
+        results: [],
+        envelope: {
+            command: input.ctx.key,
+            duration_ms: durationMs,
+            adapter_version: input.inv.adapter.version,
+            surface: input.ctx.targetSurface,
+            error: input.error,
+            ...(input.nextActionCode
+                ? {
+                    next_actions: defaultErrorNextActions(input.inv.adapter.name, input.inv.cmdName, input.nextActionCode),
+                }
+                : {}),
+        },
+        durationMs,
+        exitCode: input.exitCode,
+        warnings: input.warnings,
+        error: input.error,
+        ...(input.diagnostics ? { diagnostics: input.diagnostics } : {}),
+    };
+}
+export function validateKernelInput(inv, ctx, startedAt, warnings) {
+    const validation = ctx.compiled.validate(inv.bag.args);
+    if (validation.ok)
+        return undefined;
+    const first = validation.errors[0] ?? { message: "invalid arguments" };
+    const path = (first.instancePath ?? "").replace(/^\//, "");
+    const name = path || "args";
+    const error = {
+        code: "invalid_input",
+        message: `arg "${name}" ${first.message ?? "invalid"}`,
+        adapter_path: ctx.adapterPath,
+        step: 0,
+        suggestion: `match the JSON Schema at \`unicli describe ${inv.adapter.name} ${inv.cmdName}\``,
+        retryable: false,
+    };
+    return {
+        stage: "validate",
+        result: errorResult({
+            inv,
+            ctx,
+            startedAt,
+            warnings,
+            error,
+            exitCode: ExitCode.USAGE_ERROR,
+            nextActionCode: "invalid_input",
+        }),
+    };
+}
+export function hardenKernelInput(inv, ctx, startedAt, warnings) {
+    try {
+        const hardened = hardenArgs(inv.bag.args, ctx.compiled.argByName);
+        warnings.push(...hardened.warnings);
+        return undefined;
+    }
+    catch (err) {
+        if (!(err instanceof InputHardeningError))
+            throw err;
+        const error = {
+            code: "invalid_input",
+            message: err.message,
+            adapter_path: ctx.adapterPath,
+            step: 0,
+            suggestion: err.suggestion,
+            retryable: false,
+        };
+        return {
+            stage: "harden",
+            result: errorResult({
+                inv,
+                ctx,
+                startedAt,
+                warnings,
+                error,
+                exitCode: ExitCode.USAGE_ERROR,
+                nextActionCode: "invalid_input",
+            }),
+        };
+    }
+}
+export async function authorizeKernelInvocation(inv, ctx, startedAt, warnings) {
+    try {
+        const policy = await evaluateOperationPolicyWithApprovals({
+            site: inv.adapter.name,
+            command: inv.cmdName,
+            description: inv.command.description,
+            adapterType: inv.adapter.type,
+            targetSurface: ctx.targetSurface,
+            strategy: ctx.strategy,
+            domain: inv.command.domain ?? inv.adapter.domain,
+            base: inv.command.base ?? inv.adapter.base,
+            browser: inv.adapter.browser === true || inv.command.browser === true,
+            args: inv.command.adapterArgs,
+            profile: inv.permissionProfile,
+            approved: inv.approved,
+        });
+        if (policy.enforcement === "deny") {
+            const ruleId = policy.deny_rule?.id ?? "unknown";
+            const ruleReason = policy.deny_rule?.reason ?? "permission rule matched";
+            const error = {
+                code: "permission_denied",
+                message: `permission rule "${ruleId}" denies ${policy.effect}: ${ruleReason}`,
+                adapter_path: ctx.adapterPath,
+                step: 0,
+                suggestion: policy.approval_hint ?? "edit or remove the matching permission rule",
+                retryable: false,
+                alternatives: [
+                    `unicli --dry-run ${inv.adapter.name} ${inv.cmdName}`,
+                    "edit ~/.unicli/permission-rules.json",
+                ],
+            };
+            return {
+                stage: "authorize",
+                blocked: {
+                    stage: "authorize",
+                    result: errorResult({
+                        inv,
+                        ctx,
+                        startedAt,
+                        warnings,
+                        error,
+                        exitCode: ExitCode.AUTH_REQUIRED,
+                        nextActionCode: "permission_denied",
+                    }),
+                },
+            };
+        }
+        if (policy.enforcement === "needs_approval") {
+            const error = {
+                code: "permission_denied",
+                message: `permission profile "${policy.profile}" requires approval for ${policy.effect}`,
+                adapter_path: ctx.adapterPath,
+                step: 0,
+                suggestion: policy.approval_hint ??
+                    "rerun with --yes or use --permission-profile open",
+                retryable: false,
+                alternatives: [
+                    `unicli --dry-run ${inv.adapter.name} ${inv.cmdName}`,
+                    `unicli --yes --permission-profile ${policy.profile} ${inv.adapter.name} ${inv.cmdName}`,
+                    `unicli --permission-profile open ${inv.adapter.name} ${inv.cmdName}`,
+                ],
+            };
+            return {
+                stage: "authorize",
+                blocked: {
+                    stage: "authorize",
+                    result: errorResult({
+                        inv,
+                        ctx,
+                        startedAt,
+                        warnings,
+                        error,
+                        exitCode: ExitCode.AUTH_REQUIRED,
+                        nextActionCode: "permission_denied",
+                    }),
+                },
+            };
+        }
+        return { stage: "authorize", policy };
+    }
+    catch (err) {
+        if (err instanceof InvalidPermissionProfileError) {
+            const error = {
+                code: "invalid_input",
+                message: err.message,
+                adapter_path: ctx.adapterPath,
+                step: 0,
+                suggestion: "use one of: open, confirm, locked",
+                retryable: false,
+            };
+            return {
+                stage: "authorize",
+                blocked: {
+                    stage: "authorize",
+                    result: errorResult({
+                        inv,
+                        ctx,
+                        startedAt,
+                        warnings,
+                        error,
+                        exitCode: ExitCode.USAGE_ERROR,
+                        nextActionCode: "invalid_input",
+                    }),
+                },
+            };
+        }
+        if (err instanceof PermissionRulesConfigError) {
+            const error = {
+                code: err.code,
+                message: err.message,
+                adapter_path: ctx.adapterPath,
+                step: 0,
+                suggestion: err.suggestion,
+                retryable: false,
+            };
+            return {
+                stage: "authorize",
+                blocked: {
+                    stage: "authorize",
+                    result: errorResult({
+                        inv,
+                        ctx,
+                        startedAt,
+                        warnings,
+                        error,
+                        exitCode: ExitCode.USAGE_ERROR,
+                        nextActionCode: "invalid_input",
+                    }),
+                },
+            };
+        }
+        throw err;
+    }
+}
+export async function rememberKernelApproval(inv, policy, warnings) {
+    if (inv.rememberApproval !== true)
+        return;
+    try {
+        await rememberApproval(createApprovalStore(), { policy });
+    }
+    catch (error) {
+        warnings.push(`failed to persist approval memory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function executeKernelCommand(inv, ctx) {
+    if (inv.command.pipeline) {
+        return runPipeline(inv.command.pipeline, inv.bag, inv.adapter.base, {
+            site: inv.adapter.name,
+            command: inv.cmdName,
+            strategy: ctx.strategy,
+            domain: inv.command.domain ?? inv.adapter.domain,
+            surface: inv.surface,
+            trace_id: inv.trace_id,
+        });
+    }
+    if (inv.command.func) {
+        let page = null;
+        try {
+            if (inv.command.browser === true) {
+                const { acquirePage } = await import("../steps/browser-helpers.js");
+                page = await acquirePage({
+                    data: null,
+                    args: inv.bag.args,
+                    vars: {},
+                    base: inv.adapter.base,
+                    source: inv.bag.source,
+                    surface: inv.surface,
+                    trace_id: inv.trace_id,
+                    browserSession: inv.command.browserSession,
+                });
+            }
+            const raw = await inv.command.func(page, inv.bag.args);
+            return Array.isArray(raw) ? raw : [raw];
+        }
+        finally {
+            if (page && typeof page === "object" && "close" in page) {
+                // REASON: Browser close is post-result cleanup; a close failure must not replace the command result.
+                await Promise.resolve(page.close()).catch(() => undefined);
+            }
+        }
+    }
+    throw new Error(`command ${ctx.key} has neither pipeline nor func`);
+}
+export function malformedCommandResult(inv, ctx, startedAt, warnings) {
+    const error = {
+        code: "internal_error",
+        message: `command ${ctx.key} has neither pipeline nor func`,
+        adapter_path: ctx.adapterPath,
+        step: 0,
+        suggestion: "the adapter manifest is broken; run `unicli repair` to regenerate",
+        retryable: false,
+    };
+    return {
+        stage: "execute",
+        result: errorResult({
+            inv,
+            ctx,
+            startedAt,
+            warnings,
+            error,
+            exitCode: ExitCode.CONFIG_ERROR,
+        }),
+    };
+}
+export function executionErrorResult(inv, ctx, startedAt, warnings, err) {
+    const fields = errorToAgentFields(err, ctx.adapterPath, inv.adapter.name, inv.cmdName);
+    const error = {
+        code: errorTypeToCode(err),
+        message: err instanceof Error ? err.message : String(err),
+        ...fields,
+    };
+    const diagnostics = [
+        ...(diagnosticsForError(err) ?? []),
+        ...(browserDiagnostics(inv, ctx) ?? []),
+    ];
+    return {
+        stage: "repair-diagnostics",
+        result: errorResult({
+            inv,
+            ctx,
+            startedAt,
+            warnings,
+            error,
+            exitCode: mapErrorToExitCode(err),
+            nextActionCode: error.code,
+            ...(diagnostics.length > 0 ? { diagnostics } : {}),
+        }),
+    };
+}
+export function successKernelResult(inv, ctx, startedAt, warnings, results) {
+    const durationMs = Date.now() - startedAt;
+    const diagnostics = browserDiagnostics(inv, ctx);
+    return {
+        results,
+        envelope: {
+            command: ctx.key,
+            duration_ms: durationMs,
+            adapter_version: inv.adapter.version,
+            surface: ctx.targetSurface,
+            next_actions: defaultSuccessNextActions(inv.adapter.name, inv.cmdName, {
+                supportsPagination: inv.command.paginated === true,
+            }),
+        },
+        durationMs,
+        exitCode: results.length === 0 ? ExitCode.EMPTY_RESULT : ExitCode.SUCCESS,
+        warnings,
+        ...(diagnostics ? { diagnostics } : {}),
+    };
+}
+//# sourceMappingURL=stages.js.map

package/dist/engine/kernel/stages.js.map

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

package/dist/engine/kernel/types.d.ts

@@ -50,7 +50,7 @@ export interface InvocationResult {
     error?: AgentError;
     diagnostics?: InvocationDiagnostic[];
 }
-export type InvocationDiagnostic = RuntimePermissionDeniedDiagnostic;
+export type InvocationDiagnostic = RuntimePermissionDeniedDiagnostic | BrowserCommandDiagnostic;
 export interface RuntimePermissionDeniedDiagnostic {
     kind: "runtime_permission_denied";
     code: "permission_denied";
@@ -61,4 +61,24 @@ export interface RuntimePermissionDeniedDiagnostic {
     resource_buckets: string[];
     resources?: Record<string, string[]>;
 }
+export interface BrowserCommandDiagnostic {
+    kind: "browser_command";
+    site: string;
+    command: string;
+    adapter_path: string;
+    target_surface: string;
+    evidence: {
+        session: string;
+        network: string;
+        verify: string;
+    };
+    site_memory: {
+        endpoints: string;
+        field_map: string;
+        notes: string;
+        fixtures_dir: string;
+        verify_dir: string;
+    };
+    authoring_loop: string[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/engine/kernel/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engine/kernel/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,YAAY,CAAC;IAClB,OAAO,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC,GAAG,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,QAAQ,EAAE,CACR,IAAI,EAAE,OAAO,KAEX;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GACZ;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAA;KAAE,CAAC;CACjE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,oBAAoB,GAAG,iCAAiC,CAAC;AAErE,MAAM,WAAW,iCAAiC;IAChD,IAAI,EAAE,2BAA2B,CAAC;IAClC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACtC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engine/kernel/types.ts"],"names":[],"mappings":"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"}

package/dist/engine/normalizer/patent-envelope.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @owner       src::engine::normalizer::patent-envelope
+ * @does        Helpers that convert per-site raw responses into the canonical PatentRecord shape; each upstream office is mapped through a dedicated normalizer (uspto / epo / jpo / kipris / inpi-fr / dpma / ipaustralia / lens / google-patents-bq / pqai / patsnap / cnipa / espacenet / cipo / inpi-br / fips); also exposes `extractKindCode` for callers that need to derive the ST.16 kind suffix from an already-segmented publication number.
+ * @needs       src/types/patent.ts
+ * @feeds       src/adapters/**, src/commands/patent.ts (cross-source fan-out + dedupe), src/engine/steps/map.ts when adapters declare `map: { _normalizer: <site> }`
+ * @breaks      throws NormalizerError on missing identity fields (publication_number) — adapters must surface a structured PATENT_SCHEMA_DRIFT envelope rather than yield a half-built PatentRecord
+ * @invariants  output is structurally a PatentRecord; dates serialized as ISO-8601; publication_number canonicalized to ST.16 segments (CC-serial-kind) where the upstream allows
+ * @side-effects none — pure functions
+ * @perf        O(N) over the raw payload size
+ * @concurrency safe (pure)
+ * @test        tests/unit/engine/normalizer/patent-envelope.test.ts
+ * @stability   stable
+ * @since       2026-05-18
+ */
+import type { PatentRecord, PatentEnvelope, PatentErrorCode } from "../../types/patent.js";
+export declare class NormalizerError extends Error {
+    readonly source_adapter: string;
+    readonly missing: string[];
+    constructor(source_adapter: string, missing: string[], message: string);
+}
+/**
+ * Canonicalize a publication number to ST.16-style segments separated by `-`.
+ * Examples: `US20240123456A1` → `US-20240123456-A1`; `EP4123456A1` → `EP-4123456-A1`.
+ * Inputs already in segmented form pass through unchanged.
+ */
+export declare function canonicalizePublicationNumber(raw: string): string;
+/**
+ * Extract the ST.16 kind code (A1, A2, B1, B2, U1, …) from a publication
+ * number. Accepts both segmented (`US-20240123456-A1`) and compact
+ * (`US20240123456A1`) inputs. Returns `undefined` when the input cannot be
+ * parsed — callers must not synthesise a kind code from nothing.
+ */
+export declare function extractKindCode(publicationNumber: string): string | undefined;
+/**
+ * Assemble a PatentRecord from partial site-supplied fields. Throws
+ * NormalizerError when `publication_number` or `source_adapter` is absent.
+ * Always stamps `retrieved_at` with the current UTC ISO-8601 timestamp.
+ */
+export declare function assemblePatentRecord(partial: Partial<PatentRecord> & {
+    publication_number: string;
+    source_adapter: string;
+}): PatentRecord;
+/**
+ * Build a structured error envelope for stderr surfacing. The exit_code is
+ * derived from the code class: AUTH=77, RATE_LIMIT=75, NOT_FOUND=66,
+ * DEPRECATED=69, default 1.
+ */
+export declare function buildPatentEnvelope(input: {
+    code: PatentErrorCode;
+    adapter_path: string;
+    step: string;
+    suggestion: string;
+    alternatives?: string[];
+    retryable?: boolean;
+}): PatentEnvelope;
+/**
+ * Dedupe a batch of records by family_id; when family_id is missing fall back
+ * to canonical publication_number. Preserves first-seen ordering.
+ */
+export declare function dedupeByFamily(records: PatentRecord[]): PatentRecord[];
+//# sourceMappingURL=patent-envelope.d.ts.map

package/dist/engine/normalizer/patent-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patent-envelope.d.ts","sourceRoot":"","sources":["../../../src/engine/normalizer/patent-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,cAAc,EAAE,MAAM;aACtB,OAAO,EAAE,MAAM,EAAE;gBADjB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EAAE,EACjC,OAAO,EAAE,MAAM;CAKlB;AAMD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqBjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU7E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB,GACA,YAAY,CAmBd;AAeD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,IAAI,EAAE,eAAe,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,cAAc,CAUjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAYtE"}