@uipath/maestro-builder-sdk 5.2.0

package/dist/case/entry-points.d.ts

@@ -0,0 +1,79 @@
+/**
+ * case/entry-points — project a case's In/Out args into the sibling
+ * `entry-points.json` `input`/`output` JSON-Schemas.
+ *
+ * The runtime discovers a case's start points (triggers) from `entry-points.json`,
+ * and Studio Web reads each entry's `input`/`output` schema to render the run
+ * form. `compile-cli` keeps that file in step with the caseplan. This module is
+ * the pure projection: caseplan `variables` (+ a trigger id) → `{ input, output }`.
+ *
+ * The type→format mapping mirrors the platform's `getTypeAndFormatForType`
+ * (PackagingUtil), ported from the `uipath-maestro-case` skill's
+ * `entry-points-sync.md`:
+ *
+ *   string   → { type: 'string' }
+ *   integer  → { type: 'integer' }
+ *   boolean  → { type: 'boolean' }
+ *   float    → { type: 'number', format: 'float' }
+ *   double   → { type: 'number', format: 'double' }
+ *   date     → { type: 'string', format: 'date' }
+ *   datetime → { type: 'string', format: 'date-time' }
+ *   file     → { $ref: '#/definitions/job-attachment' } (+ a `definitions` block)
+ *   jsonSchema → the variable's `body` (minus `$schema`)
+ *
+ * Scalars/date/datetime/float/double carry `title` = the var name, and `default`
+ * only when truthy (verbatim string, never coerced). `file`/`jsonSchema` carry
+ * neither. An entry's `input` is scoped to the In-args bound to THAT trigger (by
+ * `elementId`); its `output` projects every Out-arg (default from the Out-arg's
+ * `inputOutputs` companion).
+ */
+/** The fixed JobAttachment definition a `file` property `$ref`s into. */
+export declare const JOB_ATTACHMENT_DEFINITION: {
+    readonly type: "object";
+    readonly properties: {
+        readonly ID: {
+            readonly type: "string";
+            readonly description: "Orchestrator attachment key";
+        };
+        readonly FullName: {
+            readonly type: "string";
+            readonly description: "File name";
+        };
+        readonly MimeType: {
+            readonly type: "string";
+            readonly description: "The MIME type of the content, such as \"application/json\" or \"image/png";
+        };
+        readonly Metadata: {
+            readonly type: "object";
+            readonly description: "Dictionary<string, string> of metadata";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly required: readonly ["ID"];
+    readonly 'x-uipath-resource-kind': "JobAttachment";
+};
+interface Var {
+    name?: string;
+    type?: string;
+    default?: unknown;
+    elementId?: string;
+    required?: boolean;
+    body?: unknown;
+}
+interface CaseVariables {
+    inputs?: Var[];
+    outputs?: Var[];
+    inputOutputs?: Var[];
+}
+/**
+ * Project a case's variables into one trigger's `{ input, output }`. `input` holds
+ * the In-args bound to `triggerId`; `output` holds every Out-arg (with its default
+ * pulled from the root `inputOutputs` companion).
+ */
+export declare function entryPointIO(variables: CaseVariables | undefined, triggerId: string): {
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+};
+export {};

package/dist/case/entry-points.js

@@ -0,0 +1,118 @@
+/**
+ * case/entry-points — project a case's In/Out args into the sibling
+ * `entry-points.json` `input`/`output` JSON-Schemas.
+ *
+ * The runtime discovers a case's start points (triggers) from `entry-points.json`,
+ * and Studio Web reads each entry's `input`/`output` schema to render the run
+ * form. `compile-cli` keeps that file in step with the caseplan. This module is
+ * the pure projection: caseplan `variables` (+ a trigger id) → `{ input, output }`.
+ *
+ * The type→format mapping mirrors the platform's `getTypeAndFormatForType`
+ * (PackagingUtil), ported from the `uipath-maestro-case` skill's
+ * `entry-points-sync.md`:
+ *
+ *   string   → { type: 'string' }
+ *   integer  → { type: 'integer' }
+ *   boolean  → { type: 'boolean' }
+ *   float    → { type: 'number', format: 'float' }
+ *   double   → { type: 'number', format: 'double' }
+ *   date     → { type: 'string', format: 'date' }
+ *   datetime → { type: 'string', format: 'date-time' }
+ *   file     → { $ref: '#/definitions/job-attachment' } (+ a `definitions` block)
+ *   jsonSchema → the variable's `body` (minus `$schema`)
+ *
+ * Scalars/date/datetime/float/double carry `title` = the var name, and `default`
+ * only when truthy (verbatim string, never coerced). `file`/`jsonSchema` carry
+ * neither. An entry's `input` is scoped to the In-args bound to THAT trigger (by
+ * `elementId`); its `output` projects every Out-arg (default from the Out-arg's
+ * `inputOutputs` companion).
+ */
+/** The fixed JobAttachment definition a `file` property `$ref`s into. */
+export const JOB_ATTACHMENT_DEFINITION = {
+    type: 'object',
+    properties: {
+        ID: { type: 'string', description: 'Orchestrator attachment key' },
+        FullName: { type: 'string', description: 'File name' },
+        MimeType: { type: 'string', description: 'The MIME type of the content, such as "application/json" or "image/png' },
+        Metadata: { type: 'object', description: 'Dictionary<string, string> of metadata', additionalProperties: { type: 'string' } },
+    },
+    required: ['ID'],
+    'x-uipath-resource-kind': 'JobAttachment',
+};
+const JOB_ATTACHMENT_REF = '#/definitions/job-attachment';
+/** The JSON-Schema property for one variable. `file` → `$ref`; others get title + default. */
+function propertyForVar(v) {
+    const type = normalizeType(v.type);
+    if (type === 'file')
+        return { $ref: JOB_ATTACHMENT_REF };
+    if (type === 'jsonSchema') {
+        const body = (v.body && typeof v.body === 'object' ? { ...v.body } : {});
+        delete body.$schema;
+        return body;
+    }
+    // Build in the platform's key order: type, format, title, default.
+    const out = {};
+    const tf = TYPE_FORMAT[type];
+    if (tf) {
+        out.type = tf.type;
+        if (tf.format)
+            out.format = tf.format;
+    }
+    else {
+        out.type = type; // string / integer / boolean / number / unknown → bare type
+    }
+    out.title = v.name;
+    if (v.default)
+        out.default = v.default; // only when truthy; verbatim
+    return out;
+}
+const TYPE_FORMAT = {
+    string: { type: 'string' },
+    integer: { type: 'integer' },
+    boolean: { type: 'boolean' },
+    number: { type: 'number' },
+    float: { type: 'number', format: 'float' },
+    double: { type: 'number', format: 'double' },
+    date: { type: 'string', format: 'date' },
+    datetime: { type: 'string', format: 'date-time' },
+};
+function normalizeType(t) {
+    return t === 'octet-stream' ? 'file' : t ?? 'string';
+}
+/** Build one `{ type:'object', properties, required, definitions? }` schema from a var list. */
+function objectSchema(vars) {
+    const properties = {};
+    const required = [];
+    let hasFile = false;
+    for (const v of vars) {
+        if (!v.name)
+            continue;
+        properties[v.name] = propertyForVar(v);
+        if (normalizeType(v.type) === 'file')
+            hasFile = true;
+        if (v.required)
+            required.push(v.name);
+    }
+    const schema = { type: 'object', properties, required };
+    if (hasFile)
+        schema.definitions = { 'job-attachment': JOB_ATTACHMENT_DEFINITION };
+    return schema;
+}
+/**
+ * Project a case's variables into one trigger's `{ input, output }`. `input` holds
+ * the In-args bound to `triggerId`; `output` holds every Out-arg (with its default
+ * pulled from the root `inputOutputs` companion).
+ */
+export function entryPointIO(variables, triggerId) {
+    const vars = variables ?? {};
+    const inArgs = (vars.inputs ?? []).filter((v) => v.elementId === triggerId);
+    const companionDefault = new Map();
+    for (const c of vars.inputOutputs ?? [])
+        if (c.name && c.elementId === 'root' && c.default !== undefined)
+            companionDefault.set(c.name, c.default);
+    const outArgs = (vars.outputs ?? []).map((o) => ({
+        ...o,
+        default: o.default ?? (o.name ? companionDefault.get(o.name) : undefined),
+    }));
+    return { input: objectSchema(inArgs), output: objectSchema(outArgs) };
+}

package/dist/case/format-profile.d.ts

@@ -0,0 +1,60 @@
+import type { SchemaVersionPolicy } from '../schema-version.js';
+/** The serializer-owned Case JSON grammar contract. */
+export interface CaseFormatProfile {
+    writeVersion: string;
+    publishVersion: number;
+    nodeTypeField: 'type';
+    triggerNodeType: string;
+    triggerBagField: 'uipath' | 'inputs';
+    triggerLabelField: 'label' | 'display';
+    triggerTypeVersion?: string;
+    timerServiceType: 'Intsvc.TimerTrigger' | 'timer';
+    eventServiceType: 'Intsvc.EventTrigger';
+    waitConnectorServiceType: 'Intsvc.WaitForEvent';
+    connectorActivityServiceType: 'Intsvc.ActivityExecution';
+    externalAgentSyncServiceType: 'Intsvc.SyncAgentExecution';
+    externalAgentAsyncServiceType: 'Intsvc.AsyncAgentExecution';
+    externalWorkflowSyncServiceType: 'Intsvc.SyncWorkflowExecution';
+    externalWorkflowAsyncServiceType: 'Intsvc.AsyncWorkflowExecution';
+    stageNodeType: string;
+    stageLabelField: 'label';
+    exceptionStageField: 'type' | 'data.stageType';
+    exceptionStageValue: string;
+    connectorActivityNodeType: string;
+    selectedStageField: 'selectedStageId' | 'selectedStageIds';
+    selectedStageCardinality: 'singular' | 'array';
+    waitConnectorRuleBagField: 'uipath';
+    layoutPolicy: 'inline' | 'sidecar';
+    requireSlaDisplayNames: boolean;
+    migrationDependencies: readonly {
+        featureFlag: string;
+        fromVersion: string;
+    }[];
+    validationCeiling: {
+        caseSchemaVersion: string;
+        formatVersion: string;
+    };
+}
+export declare const CASE_FORMAT_PROFILE: Readonly<CaseFormatProfile>;
+/**
+ * Which Case JSON schema versions `.schemaVersion()` may declare.
+ *
+ * ONE, and that is the honest answer rather than a placeholder. Case is a
+ * closed, whole-document schema: `@uipath/case-schema` ships a chain of 31
+ * grammars (`case-schema-census.json`'s `versionChain`), each with its own
+ * forward migration, and a version is a claim that the entire document matches
+ * that grammar. This SDK emits the V30 grammar natively — the V30 rule schemas
+ * `z.never` the singular `selectedStageId` that a V20 document would carry, so
+ * the older shapes are not something the current emitter can reach by writing a
+ * different number on the same bytes. `.schemaVersion('30.0.0')` is therefore
+ * an explicit restatement of what gets written, which is what makes a decompile
+ * able to PRESERVE it, and an older version is refused with the reason instead
+ * of being stamped onto V30 bytes.
+ *
+ * A second row lands here the day the emitter can write a second grammar — the
+ * `migrationDependencies` above are the same shape of statement one version
+ * further in (a feature that only exists from a given version onward).
+ */
+export declare const CASE_SCHEMA_VERSIONS: SchemaVersionPolicy;
+export declare function recordAuthoredCaseVersion(built: object, version: string): void;
+export declare function authoredCaseVersion(built: object): string | undefined;

package/dist/case/format-profile.js

@@ -0,0 +1,79 @@
+export const CASE_FORMAT_PROFILE = {
+    writeVersion: '30.0.0',
+    publishVersion: 2,
+    nodeTypeField: 'type',
+    triggerNodeType: 'uipath.case.trigger',
+    triggerBagField: 'inputs',
+    triggerLabelField: 'display',
+    triggerTypeVersion: '1.0.0',
+    timerServiceType: 'timer',
+    eventServiceType: 'Intsvc.EventTrigger',
+    waitConnectorServiceType: 'Intsvc.WaitForEvent',
+    connectorActivityServiceType: 'Intsvc.ActivityExecution',
+    externalAgentSyncServiceType: 'Intsvc.SyncAgentExecution',
+    externalAgentAsyncServiceType: 'Intsvc.AsyncAgentExecution',
+    externalWorkflowSyncServiceType: 'Intsvc.SyncWorkflowExecution',
+    externalWorkflowAsyncServiceType: 'Intsvc.AsyncWorkflowExecution',
+    stageNodeType: 'case-management:Stage',
+    stageLabelField: 'label',
+    exceptionStageField: 'data.stageType',
+    exceptionStageValue: 'secondary',
+    connectorActivityNodeType: 'execute-connector-activity',
+    selectedStageField: 'selectedStageIds',
+    selectedStageCardinality: 'array',
+    waitConnectorRuleBagField: 'uipath',
+    layoutPolicy: 'sidecar',
+    requireSlaDisplayNames: true,
+    migrationDependencies: [
+        { featureFlag: 'canvas-useExplicitEntryExitConditions', fromVersion: '12.0.0' },
+        { featureFlag: 'canvas-caseUnifiedSchema', fromVersion: '20.0.0' },
+    ],
+    validationCeiling: {
+        caseSchemaVersion: '0.1016.2',
+        formatVersion: '30.0.0',
+    },
+};
+/**
+ * Which Case JSON schema versions `.schemaVersion()` may declare.
+ *
+ * ONE, and that is the honest answer rather than a placeholder. Case is a
+ * closed, whole-document schema: `@uipath/case-schema` ships a chain of 31
+ * grammars (`case-schema-census.json`'s `versionChain`), each with its own
+ * forward migration, and a version is a claim that the entire document matches
+ * that grammar. This SDK emits the V30 grammar natively — the V30 rule schemas
+ * `z.never` the singular `selectedStageId` that a V20 document would carry, so
+ * the older shapes are not something the current emitter can reach by writing a
+ * different number on the same bytes. `.schemaVersion('30.0.0')` is therefore
+ * an explicit restatement of what gets written, which is what makes a decompile
+ * able to PRESERVE it, and an older version is refused with the reason instead
+ * of being stamped onto V30 bytes.
+ *
+ * A second row lands here the day the emitter can write a second grammar — the
+ * `migrationDependencies` above are the same shape of statement one version
+ * further in (a feature that only exists from a given version onward).
+ */
+export const CASE_SCHEMA_VERSIONS = {
+    family: 'case',
+    mode: 'enumerated',
+    method: '.schemaVersion',
+    default: CASE_FORMAT_PROFILE.writeVersion,
+    latestKnown: CASE_FORMAT_PROFILE.validationCeiling.formatVersion,
+    migration: 'Case documents migrate FORWARD on read, through the platform\'s feature-flag-gated chain; there is no '
+        + '`uip maestro case migrate`, and no path that writes an older grammar.',
+    writable: [
+        {
+            version: CASE_FORMAT_PROFILE.writeVersion,
+            evidence: 'The grammar this serializer emits natively, asserted construct by construct by '
+                + 'scripts/audit-case-coverage.mjs against case-schema-census.json for the pinned write version.',
+        },
+    ],
+};
+// Preserve deprecated-method provenance for check() without adding an emitted
+// or publicly documented field to BuiltCase.
+const authoredVersions = new WeakMap();
+export function recordAuthoredCaseVersion(built, version) {
+    authoredVersions.set(built, version);
+}
+export function authoredCaseVersion(built) {
+    return authoredVersions.get(built);
+}

package/dist/case/ids.d.ts

@@ -0,0 +1,24 @@
+/**
+ * case/ids — deterministic ID generation for caseplan.json (schema V30).
+ *
+ * The Case schema (see @uipath/case-schema) uses `prefixedId`-style IDs: a fixed
+ * prefix followed by N characters from the base-62 alphabet. The frontend and
+ * validator only depend on the *format* (e.g. the case id must match
+ * `/^case-[A-Za-z0-9]{10}$/`); the suffix need only be unique within the file.
+ *
+ * A builder should emit *stable, diffable* output, so instead of random
+ * suffixes we derive them deterministically from a seed string (the entity's
+ * logical path). Same input → same caseplan.json every compile. A uniqueness
+ * guard salts-and-rehashes on the (astronomically unlikely) collision.
+ */
+/** Per-file ID allocator: prefix + deterministic base-62 suffix, unique within the file. */
+export declare class IdGen {
+    private readonly used;
+    /** Allocate an id `<prefix><suffix>` where suffix is `len` base-62 chars derived from `seed`. */
+    make(prefix: string, len: number, seed: string): string;
+    caseId(seed: string): string;
+    stageId(seed: string): string;
+    taskId(seed: string): string;
+    conditionId(seed: string): string;
+    ruleId(seed: string): string;
+}

package/dist/case/ids.js

@@ -0,0 +1,76 @@
+/**
+ * case/ids — deterministic ID generation for caseplan.json (schema V30).
+ *
+ * The Case schema (see @uipath/case-schema) uses `prefixedId`-style IDs: a fixed
+ * prefix followed by N characters from the base-62 alphabet. The frontend and
+ * validator only depend on the *format* (e.g. the case id must match
+ * `/^case-[A-Za-z0-9]{10}$/`); the suffix need only be unique within the file.
+ *
+ * A builder should emit *stable, diffable* output, so instead of random
+ * suffixes we derive them deterministically from a seed string (the entity's
+ * logical path). Same input → same caseplan.json every compile. A uniqueness
+ * guard salts-and-rehashes on the (astronomically unlikely) collision.
+ */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'; // 62
+/** FNV-1a 64-bit hash of a string → bigint. Deterministic, well-distributed. */
+function fnv1a64(s) {
+    let h = 0xcbf29ce484222325n;
+    const mask = 0xffffffffffffffffn;
+    for (let i = 0; i < s.length; i++) {
+        h ^= BigInt(s.charCodeAt(i));
+        h = (h * 0x100000001b3n) & mask;
+    }
+    return h;
+}
+/** Encode a hash into `len` base-62 characters. */
+function base62(seed, len) {
+    let x = fnv1a64(seed);
+    // Mix in the length so different-length requests for the same seed diverge.
+    x ^= BigInt(len) * 0x9e3779b97f4a7c15n;
+    x &= 0xffffffffffffffffn;
+    const base = BigInt(ALPHABET.length);
+    let out = '';
+    for (let i = 0; i < len; i++) {
+        out += ALPHABET[Number(x % base)];
+        x = x / base;
+        if (x === 0n)
+            x = fnv1a64(seed + '#' + i); // re-seed if exhausted (long ids)
+    }
+    return out;
+}
+/** Per-file ID allocator: prefix + deterministic base-62 suffix, unique within the file. */
+export class IdGen {
+    used = new Set();
+    /** Allocate an id `<prefix><suffix>` where suffix is `len` base-62 chars derived from `seed`. */
+    make(prefix, len, seed) {
+        for (let salt = 0;; salt++) {
+            const id = prefix + base62(salt === 0 ? seed : `${seed}~${salt}`, len);
+            if (!this.used.has(id)) {
+                this.used.add(id);
+                return id;
+            }
+        }
+    }
+    caseId(seed) {
+        // Decompile feeds an already-emitted root id back through casePlan(). The
+        // wire form is unambiguous and may be reserved verbatim; authored logical
+        // ids still take the deterministic hash path below.
+        if (/^case-[A-Za-z0-9]{10}$/.test(seed)) {
+            this.used.add(seed);
+            return seed;
+        }
+        return this.make('case-', 10, seed);
+    }
+    stageId(seed) {
+        return this.make('Stage_', 6, seed);
+    }
+    taskId(seed) {
+        return this.make('t', 8, seed);
+    }
+    conditionId(seed) {
+        return this.make('Condition_', 6, seed);
+    }
+    ruleId(seed) {
+        return this.make('Rule_', 6, seed);
+    }
+}

package/dist/case/load.d.ts

@@ -0,0 +1,12 @@
+import type { BuiltCase } from './case-sdk.js';
+/**
+ * Resolve a user argument (a `.ts` path or a BaseName) to a case source file.
+ *
+ * Candidates must be FILES: the authoring workspace always has a directory named
+ * `<Name>` beside `<Name>.case.ts` (created by `uip solution init <Name>`), and
+ * the family-first check/compile commands pass the bare basename. A plain `existsSync()` is true for
+ * that directory, so the bare name resolved to it and Node failed with
+ * "Directory import ... is not supported".
+ */
+export declare function resolveCaseFile(arg: string): string;
+export declare function loadBuiltCase(file: string): Promise<BuiltCase>;

package/dist/case/load.js

@@ -0,0 +1,32 @@
+/** Shared: dynamic-import an authored case module and return its BuiltCase. */
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+/**
+ * Resolve a user argument (a `.ts` path or a BaseName) to a case source file.
+ *
+ * Candidates must be FILES: the authoring workspace always has a directory named
+ * `<Name>` beside `<Name>.case.ts` (created by `uip solution init <Name>`), and
+ * the family-first check/compile commands pass the bare basename. A plain `existsSync()` is true for
+ * that directory, so the bare name resolved to it and Node failed with
+ * "Directory import ... is not supported".
+ */
+export function resolveCaseFile(arg) {
+    const candidates = [arg, `${arg}.case.ts`, `${arg}.ts`];
+    for (const c of candidates) {
+        const resolved = resolve(c);
+        if (existsSync(resolved) && statSync(resolved).isFile())
+            return resolved;
+    }
+    throw new Error(`case source not found: tried ${candidates.join(', ')}`);
+}
+export async function loadBuiltCase(file) {
+    const mod = await import(pathToFileURL(file).href);
+    const exp = mod.default ?? mod.casePlan ?? mod.case;
+    if (!exp)
+        throw new Error(`${file} has no default export. Add: export default casePlan('id')...build();`);
+    const built = typeof exp.build === 'function' ? exp.build() : exp;
+    if (!built || !Array.isArray(built.stages))
+        throw new Error(`${file} default export is not a built case. Did you call .build()?`);
+    return built;
+}

package/dist/case/preserve.d.ts

@@ -0,0 +1,133 @@
+import type { BuiltCase } from './case-sdk.js';
+export type PreservedVariableLane = 'inputs' | 'outputs' | 'inputOutputs';
+/** One platform-owned node retained at its original position in `nodes[]`. */
+export interface PreservedCaseNode {
+    /** Original zero-based position in the top-level `nodes[]` array. */
+    index: number;
+    /** Opaque annotation node. */
+    node: Record<string, unknown>;
+}
+/** Platform-owned task identity fields keyed by stage label, lane, and task name. */
+/** Locates one rebuilt task, the way `taskFields` entries do. */
+export interface PreservedTaskRef {
+    /** Stage label used to find the rebuilt task. */
+    stage: string;
+    /** Zero-based task lane. */
+    lane: number;
+    /** Task display name used to find the rebuilt task. */
+    task: string;
+}
+export interface PreservedTaskFields extends PreservedTaskRef {
+    /** Wire-only fields; the preservation contract permits `elementId` only. */
+    fields: Record<string, unknown>;
+}
+interface ConditionIdentity {
+    id?: string;
+    rules?: Array<Array<{
+        id?: string;
+    }>>;
+}
+interface SlaIdentity {
+    id?: string;
+    escalations?: Array<{
+        id?: string;
+    }>;
+}
+interface StageIdentity {
+    label: string;
+    id?: string;
+    tasks?: Array<Array<{
+        name: string;
+        id?: string;
+        entryConditions?: ConditionIdentity[];
+        inputs?: Array<{
+            name: string;
+            id?: string;
+        }>;
+        outputs?: Array<{
+            name: string;
+            id?: string;
+        }>;
+    }>>;
+    entryConditions?: ConditionIdentity[];
+    exitConditions?: ConditionIdentity[];
+    slaRules?: SlaIdentity[];
+}
+interface CaseIdentityPreservation {
+    id?: string;
+    triggers?: Array<{
+        id?: string;
+    }>;
+    stages?: StageIdentity[];
+    caseExitRules?: ConditionIdentity[];
+    slaRules?: SlaIdentity[];
+    variables?: Partial<Record<PreservedVariableLane, Array<{
+        name: string;
+        id?: string;
+    }>>>;
+}
+/**
+ * Non-authoring Case JSON lanes retained by decompile/recompile.
+ *
+ * This intentionally cannot carry stages, tasks, known metadata, or known
+ * variable fields. Those constructs must use the typed builder or fail with a
+ * named refusal.
+ */
+export interface CaseJsonPreservation {
+    /** Unknown document-root fields. */
+    topLevel?: Record<string, unknown>;
+    /** Unknown metadata fields, including Case Manager configuration. */
+    metadata?: Record<string, unknown>;
+    /** Platform-owned fields nested inside an otherwise typed Case App config. */
+    caseAppConfigFields?: {
+        fields?: Record<string, unknown>;
+        sections?: Array<{
+            id: string;
+            fields: Record<string, unknown>;
+        }>;
+    };
+    /** Platform-owned annotation nodes. */
+    nodes?: PreservedCaseNode[];
+    /** Original ordering of typed and preserved top-level nodes. */
+    nodeOrder?: string[];
+    /** Opaque diagram edges. */
+    edges?: unknown[];
+    /** Opaque V30 layout side-car. */
+    layout?: unknown;
+    /** Preserve the absence of a layout side-car on a foreign document. */
+    omitLayout?: boolean;
+    /** Designer-internal variable fields keyed by lane and variable name. */
+    variableFields?: Partial<Record<PreservedVariableLane, Record<string, Record<string, unknown>>>>;
+    /**
+     * Legacy non-string defaults retained by decompile/recompile. Each value must
+     * JSON-encode to the serializer-owned string default for the same variable.
+     */
+    legacyVariableDefaults?: Partial<Record<PreservedVariableLane, Record<string, unknown>>>;
+    /** Original variable row order for each lane. */
+    variableOrder?: Partial<Record<PreservedVariableLane, string[]>>;
+    /** Wire-only task identity fields aligned without authoring them. */
+    taskFields?: PreservedTaskFields[];
+    /** Platform-owned trigger data fields aligned by trigger order. */
+    triggerDataFields?: Array<Record<string, unknown>>;
+    /** Stage labels whose source JSON intentionally omitted inline positions. */
+    omitStagePositions?: string[];
+    /**
+     * Tasks whose source JSON carried no `elementId`. The serializer stamps one on
+     * every task, so a document predating the field (the V20-era corpus) would
+     * otherwise gain one on round-trip — and gaining one is not cosmetic: the
+     * converter matches a task's io rows against it, so adding it can newly wire
+     * outputs that were dead in the original. Recording the omission keeps
+     * `decompile` → `compile` converter-equivalent, which is the brownfield
+     * contract; greenfield authoring still always gets one.
+     */
+    omitTaskElementIds?: PreservedTaskRef[];
+    /** Opaque wire identities aligned to typed constructs by name and position. */
+    identities?: CaseIdentityPreservation;
+}
+/** Attach decompiler-owned, non-authoring wire data to a built case. */
+export declare function preserveCaseJson(built: BuiltCase, payload: CaseJsonPreservation): BuiltCase;
+/** @internal Read the preservation payload attached by `preserveCaseJson`. */
+export declare function caseJsonPreservation(built: BuiltCase): CaseJsonPreservation | undefined;
+/** @internal Validate that preservation cannot impersonate typed authoring. */
+export declare function caseJsonPreservationErrors(payload: CaseJsonPreservation | undefined): string[];
+export {};