# Source Migration Guide — the export's catalogs, credentials and source steps at execution

Execution of an extracted genome migrates what the genome body leaves out: the source automation's **UI targets** (selectors) and **test data**. Both come from the export the Source Map names ([extracted-genome-guide.md § Source Map](extracted-genome-guide.md)); execution derives its catalogs from that export at build time. This guide derives them and says what each kind of source step becomes; the UI targets: [ui-target-migration-guide.md](ui-target-migration-guide.md); the test data: [test-execution-guide.md](test-execution-guide.md).

## Migration preflight — derive the catalogs from the export

Source Map names framework, export path and identity, and every step's source objects. Execution turns that into working catalogs once, before the first UI group:

1. Resolve the export and the framework migration pack: the recorded export path, or the paths the user gave to the scaffolding questions ([execution-guide.md § 1.3](execution-guide.md)); confirm the export's identity against the Source Map (manifest, version, process count) and select the pack's framework row ([SKILL.md § Source Frameworks](../SKILL.md)). Report a mismatch and let the user decide; a missing or declined export or pack ends the migration part of the run — live capture where the application is reachable, placeholders otherwise, stated in the report.
2. Run the source guide's inventory commands (its § UI Target Locators and § Test Data name them and the files they write) into the build's working folder `<solution or project>/migration/source/`, never beside the genome.
3. Check the step tables against this export: `python3 "<SKILL_DIR>/scripts/check-genome.py" <process|component> "<GENOME_MD>" --processes "<PROCESS_INVENTORY>" --recordsets "<RECORDSET_LIST>"` (`python` on Windows), with the two files step 2 wrote. Each component genome's step table (the Source Map's `### Steps`, [extracted-genome-guide.md § Source Map](extracted-genome-guide.md)) pairs every workflow step with its source objects `` `Name` (id) ``, the data sets they read and their captures; the check proves every one resolves in the export execution resolved. Execution never edits the genome: a `FAIL` line is a genome deviation, reported for an extraction edit, and the build maps that step by hand meanwhile and records the mapping.
3a. **Write the target spec per component, once**, when the build has UI activities: [ui-target-migration-guide.md § Target spec](ui-target-migration-guide.md).
4. **Check the source facts the genome cites, before any group builds on them.** A gap of the rendering the genome was extracted through is otherwise built as behaviour, silently ([extracted-genome-guide.md § Source values](extracted-genome-guide.md)). First run the source guide's renderer self-test when it has one; a failing self-test means every reading of that export's values is suspect until the renderer is fixed. Then, per workflow step, read from the step table's source objects every fact of those kinds that the step's wording or rules depend on, and record it in a source-fact table, one file per component (`migration/source/source-facts-<component>.md`: step, source object and line, genome says, source says) with one section per workflow step, a section for the configuration rows (each row or key: where it is read, what it means, and whether an empty value fails or silently changes the flow — the guard candidates of [execution-guide.md § 1.3](execution-guide.md) rule 8), one for facts shared by every step and one for deviations, so a group reads the sections of the steps it builds.

   Where the genome and the source disagree, the kind of disagreement decides what the build follows; each is recorded as a genome deviation in the group report, and the genome is left to an extraction edit:
   - criteria, literals, counts, waits and log texts follow the source — the translation carries criteria over unchanged ([selector-translation-guide.md](selector-translation-guide.md) rule 2 holds for value comparisons as for selectors);
   - a control-flow defect the genome does not mark, where the genome states the behaviour (a loop that never tests its new value, a flag never reset), follows the genome;
   - semantics neither the export nor the framework pack settles take the reading consistent with the source's production use, marked `*[Inferred]*`, with the other reading in the report.

   A count or wait that differs from an answered configuration value goes back to the user with both values; the answer is theirs. The table is regenerated with the catalogs and handed to every group with the run brief as its source for these facts; missing-detail lookups follow [execution-parts-guide.md](execution-parts-guide.md) item 6.
5. **Scrub secrets out of the derived catalogs, as part of preflight.** § Credentials keeps secrets out of the built automation, but the catalogs are derived from the export and the export holds the secret in more places than its variable table: a recorder writes the typed value into the step's own narrative (`Input "…" into the Password field`), so a step dump reproduces a password verbatim even when the variable itself was refused. Collect the secret-bearing values the source records (the source guide's § Test Data names where they live), replace every occurrence across the working folder with a mask, and re-run the scrub whenever the catalogs are regenerated. The check is one search of the build folder for the values; it belongs before the first group, not in the final review.
6. "The target catalog", "the data catalog", "the target spec" and "the source-fact table" mean these derived files; "the step table" is the genome's own. The derived files are build artifacts of the run, never committed as source of truth: the catalogs are regenerated, never edited by hand, and the target spec changes only by the entries groups add ([ui-target-migration-guide.md § Target spec](ui-target-migration-guide.md)). A catalog that sat beside the genome is stale by definition and is not read.

## Credentials

**Account identity migrates, secrets never.** Genome-side rule (one credential asset per account, never a secret value): [genome-format-guide.md § Platform Dependencies](genome-format-guide.md). At execution a login user name becomes a credential asset name (`<App>_Login_<USER>`) plus the tenant/environment URL recorded for that account, and both stay with the source's login data wherever the rebuild keeps it (a data row, a configuration value); the migration engine refuses passwords, tokens and secrets — they are entered in Orchestrator. Which account a step signs in as, and whether it signs in at all, is decided by the login data the source selects (its row, filter or configuration key), never by which credential assets exist: a selection that finds no account skips the sign-in or fails as the source does, even when an asset exists for an account the source did not select. How the build declares and reads each asset: [execution-guide.md § 2.2](execution-guide.md), credentials.

## Source steps that are not UI actions

A source's step vocabulary is wider than "click, type, read". The source guide's step table says what each kind *means* (extraction's job); this table says what execution builds for it. Only the first two rows produce a UI activity with a migrated target — which is why a migrated project has far fewer activities than the source had steps, and why an executor that emits one activity per source step produces a project several times too large.

| Kind of source step | What execution builds |
|---|---|
| Act on a control — click, type, set state | the acting activity, target from the catalog |
| Act through a packaged multi-step interaction | the pattern, not the nearest single activity ([ui-target-migration-guide.md § Composite interactions](ui-target-migration-guide.md)) |
| Wait for / assert a control is shown, with a timeout | a post-condition of the step before it → that activity's `VerifyOptions`; a Check activity only where the source branched on the outcome ([ui-verification-guide.md](ui-verification-guide.md)) |
| Assert a value — verify, compare | **read the control, then compare what it showed against the expected value.** The trap is mechanical: the source step names the control and the expected value, so a naive translation emits the expected value on both sides of the comparison and ships an assertion that can never fail. The actual side is always read at run time. The expected value and the operator come from the source's condition verbatim, like selector criteria ([selector-translation-guide.md](selector-translation-guide.md) rule 2): an equals is never loosened to a contains, and a recorded control's name is never the expected value — a recorder names a text read after what the screen showed at capture time, a sample, while the value the source compares against sits in its own condition |
| Store / read a value for later steps | a read activity writing the variable the later steps consume; a value that crosses a workflow boundary is an **argument**, not a variable |
| Set a locator's value at run time (placeholder rewriting) | a selector variable bound to the argument, not an activity ([selector-translation-guide.md](selector-translation-guide.md) rule 14 step 2) |
| Label, and the jumps that target it | **structure, not activities**: a forward jump becomes a branch that skips the steps between, a backward jump becomes a loop around them. A label with no jump to it is a comment |
| Comment | the name of the enclosing sequence or annotation — never an activity |
| Engine setting — busy check, scroll-into-view, object timeout, input method | dropped; a timeout becomes the affected activities' timeout and an input-method switch their input mode ([ui-target-migration-guide.md § Composite interactions](ui-target-migration-guide.md)) — every activity the setting reaches until the source changes it, in called workflows too; an object timeout the source never sets is its documented default, not unknown |
| A fixed pause with a value — between two steps, after a failed attempt, before a retry | kept at its value, where it acts: before a check that waits for an outcome (a Check App State, a verify with a timeout, the element wait a check became) it joins that wait — the timeout is the pause plus the source's budget for the check; before a UI action or keystrokes it is that activity's delay-before; before a screen capture, a call or a non-UI step, and where the wait is for something outside the UI (a file operation settling, a retry back-off), it is a delay. A pause the rendering shows without a value is read from the source object before it is dropped (§ Migration preflight step 4) |
| A call into a scripting wrapper's verb with an identity argument | the UI activity the verb names, on the element the identity names (target catalog, second channel); never a call into a library of verbs |
| Screen capture | a screenshot at the same point — every capture, as every log line is kept: in a test project the capture verify [test-execution-guide.md § Result parity](test-execution-guide.md) rule 3 names, or the screenshot of the checkpoint it follows; elsewhere a screenshot saved as `<workflow>-<step id>.png`, in the source's capture mode. The step's Source Map row holds the count the build is checked against |
| Log line | a log message at the same point, at the source's level and in its wording, with the values the rebuild carries substituted. A value with no counterpart in the rebuild is left out of the text — the status a wrapper action returned, which the acting activity replaces by raising on failure. An engine's own record of each step it runs (a stage log, a per-step result log) is not a log line: its counterpart is the robot's activity-level trace. A log the rebuild adds where the source had none marks a business milestone or decision (an item taken or finished, an outcome and its reason, a reply or mail sent, a count, a caught error with its context); narrating each activity is the robot's Verbose trace. The source's log file is rebuilt as well, since its readers can lie outside the export: every log point the source has also appends its line to that file, one helper workflow holding both. The file keeps the source's shape, so a rebuilt run's file compares line by line with a source run's; the lines the rebuild adds — its milestone logs, the framework's own — go to the robot's log only. Only the user's answer to the genome's Configuration Question replaces the file with the job's log in Orchestrator. A text file the source writes as data (a list a later step reads, a dump it parses) is a file write in the source's append or replace mode, whatever the source's command is called |
| Call another source process | an invoke of the workflow that process became |
| A step the source marked as skipped | dropped, unless the genome's own wording says the migration restores it — then it is built and the restoration is recorded as a deviation |

Three contracts have to be closed at the end of this translation, and each fails silently when it is left open:

- **Every out-argument the genome's Interface declares must be written on every path.** Source variables become arguments, but the step that produced one may sit in a branch, or may have been a store the migration dropped; the argument then ships declared, typed, and never assigned, and the caller reads an empty value from a workflow that validated cleanly. Seed each out-argument at the start and check at the end that every one is assigned somewhere; report the ones with no source counterpart rather than leaving them empty.
- **The source's own variable names are not the argument names.** The genome fixes the argument names; the mapping from source variable to argument is the executor's and is recorded per workflow, so a reader can trace a value back.
- **The rebuild keeps the source's names and shape; every difference has a reason.** Whoever migrated the automation compares the two side by side, and a step renamed or moved for no reason reads as a change of behaviour. A node, activity or step built from a source step the author named — a node, a stage, a test step's title — carries that name as written as its display name, emojis and numbering included where the target accepts them; a source step that has only its kind for a name (a command with no title) is named in the business's words, as a developer would name it. The source's order and branching are kept wherever the target has the same construct, and so is its tree: where the source files its objects in folders, groups or directories its owners navigate by, each workflow and test case made from an object sits at that object's path inside the project it lands in, below the part of the path the project stands for, with the path's names as written (a character a path cannot hold becomes `_`). A component groups the genome, not the tree: where several components land in one project (the test-case groups of the single test project, a library folded into its consumer, two components a split answer merges), each object keeps its own path, and components whose objects share a source folder share that folder. A workflow with no source object (a pattern helper, the configuration workflow, a failure handler) goes in a folder the build names. Which part of a path the project stands for, and which inventory field prints each object's path: the source guide's § Component Detection. A source step renamed, absorbed into another node, merged with others, split into several or dropped, and a node the rebuild adds with no source counterpart (a retry loop, a failure handler, a loop the target needs where the source worked item by item), is a row of the correspondence table (§ What the executor records) naming the target's reason: a capability the target lacks or offers, a user ruling, a source defect the genome fixes. The Source fidelity answer ([execution-guide.md § 1.3](execution-guide.md)) decides how much of this the run does: the names, the shape and the table; the names and the shape without the table; or the build's own names and grouping, each display name saying what the step does in the business's words. A display name never carries a source object id, a line number or a source variable name, and the target's internal ids stay its own. A reader traces a step to its source through its name, the correspondence table when the run keeps one, the step table and the source-fact table, a target through its target spec entry, and a decision through its ledger entry. Two things carry an id by design: a test checkpoint's id in its verify's title and message ([test-execution-guide.md § Result parity](test-execution-guide.md)), and an Object Repository element's description naming its source control ([ui-target-migration-guide.md](ui-target-migration-guide.md) rule 2).

## What the executor records (no prescribed file formats)

Mechanics — creating screens and elements, updating definitions, fuzzifying, linking — are the owning skill's Object Repository CLI and target-configuration guidance; read and use them as they are. The genome skill requires only that these facts end up recorded and reviewable:

- per UI activity: its link-table row, whose spec entry gives the source window and control it derives from (or "none"), the strict/fuzzy selector, anchor and semantic description, the confidence tier and, through the registry, the linked OR element — one OR element per distinct node, reused across workflows;
- per composite source step: pattern applied ([ui-target-migration-guide.md § Composite interactions](ui-target-migration-guide.md)), activities it expanded into, derived elements created, verify sub-step;
- per entity: its field per source column and the data sets and record counts of its seed; per data file: source data set(s) it was filled from and, per argument, whether the value came from the source, stayed at its default, or had no source counterpart; credentials appear as asset names and environments only;
- per workflow: validate result after linking, any activity still without a target;
- per interaction family: live verdict ([ui-target-migration-guide.md § Verifying targets](ui-target-migration-guide.md)) or `offline-unverified`;
- per test case: result parity table ([test-execution-guide.md § Result parity](test-execution-guide.md)) — source checkpoint, expected value, UiPath assertion, evidence, compare rule — and its counts;
- per component, when the Source fidelity answer keeps it: the correspondence table (§ Source steps that are not UI actions), `migration/correspondence/<component>.md`, holding the differences only — one row per source step the target does not build under its own name, in the source's order, and one per added node; a step built under its own name has no row. Columns `Source step | Target node | Relation | Reason`: the source step as `` `Workflow` › `Name` `` (a dash for an added node), the target node by its display name in its file, the relation (`renamed`, `absorbed into`, `merged into`, `split into`, `dropped`, `added`) and the reason. The columns are the schema every executor writes, so a scorer reads the tables of every run alike; the table is written with the component and kept current with it;
- per source command family: what it was realised as in this build — the activity class, the property encoding the package's per-activity doc prescribed, the analyzer findings accepted — fetched at the version built against ([execution-guide.md § 2.2](execution-guide.md)).

The target spec, the link table and the Object Repository registry carry the fields [ui-target-migration-guide.md](ui-target-migration-guide.md) § Target spec and § UI targets name; their file format, the run's target tool and any other scripting (mapping files, validators) are the executor's, within the authoring mode of [execution-guide.md § 2.2](execution-guide.md); the reports are the deliverable. One `migration/` folder in the build — the derived `source/` catalogs, the configuration answers, one report per project, the local feed's sources files — keeps them reviewable together and out of every project.

## Anti-patterns

1. Reading catalogs that sat beside the genome instead of deriving them from the export (§ Migration preflight); a stale copy migrates yesterday's locators.
2. Emitting one activity per source step — a Check for every wait, an assertion that compares the expected value with itself, an activity for a label or a comment (§ Source steps that are not UI actions).
3. Deriving an activity's XAML from a card snippet or from memory instead of from the default-XAML command *and* the package's per-activity doc ([execution-guide.md § 2.2](execution-guide.md)).
4. Letting a secret reach the working folder because only the variable table was refused while the step text still carries it (§ Migration preflight); shipping a declared out-argument that no path ever writes (§ Source steps that are not UI actions).
5. Building a count, a wait, a flag, a case rule or a comparison literal from the genome's wording or a rendering without reading it from the source object — an empty rendering is not an absent value, a paraphrased status text never matches the application's, and a case-insensitive test built as case-sensitive rejects valid input (§ Migration preflight step 4). Building a scripting wrapper's verbs as a library of verbs instead of UI activities on the elements its identities name ([ui-target-migration-guide.md § UI targets](ui-target-migration-guide.md), pipeline step 1).
6. Renaming a step the source author named, regrouping its steps or reordering its branches when the Source fidelity answer keeps the source's names and shape — with no correspondence row giving the target's reason when the run keeps the table — or naming a step after its source id or line (§ Source steps that are not UI actions).