Migrating a Dyalog v18.0 workspace to Link: which side should be the source of truth during two-way sync?

Direct Answer

During the initial migration, the workspace must remain the source of truth. Use ]LINK.Export to create the initial text-file tree from the workspace; this is a one-way write that establishes the file baseline without reading back. Only after verifying the exported files via Git and CI should you declare the text files authoritative and treat the workspace as disposable.

Phased Cut-Over Procedure

1. Export baseline: Run ]LINK.Export 'target-folder' from the current workspace to write all serialisable objects to .dyalog files.
2. Freeze workspace edits: Stop all saves to the shared workspace to prevent divergent versions during validation.
3. Validate files: Commit the tree to Git, perform a diff review, and run CI builds to ensure no truncation or binary blobs occurred.
4. Test round-trip: Execute )CLEAR ⋄ ]LINK.Import 'target-folder' into a fresh session to confirm all expected objects function correctly.
5. Declare files authoritative: Switch to a workflow where developers edit files directly and use ]LINK.Import to pull changes into their sessions.

Enforcing One-Way Flow

To prevent stale definitions from silently overwriting newer work during the transition, disable automatic bidirectional synchronisation:

• Disable AutoSync: Set Link.Config.AutoSync ← 0.
• Use Explicit Operations: Avoid ]LINK.Refresh (which is bidirectional) until the cut-over is complete. Use ]LINK.Export for workspace → files and ]LINK.Import for files → workspace.
• Prune Ghost Objects: Use ]LINK.Clean to remove files for objects that were deleted from the workspace during refactoring.

Handling Non-Round-Trippable Objects

In v18.0, certain object types do not serialise cleanly to text and may be skipped or emitted as stubs. These include:

• GUI namespaces (created via ⎕WC)
• ⎕OR-defined operators
• External function references (⎕NA)
• Session-only variables (e.g., ⎕BASE, ⎕IO in root)

Strategy: Because Link v18.0 does not support per-object direction, these objects should be kept in a workspace-only root. You can implement a split-root strategy by using ]LINK.Create with different target folders for serialisable and non-serialisable assets.

Verification Checklist

• Confirm version: ]LINK.Version should report 18.0.x.
• Verify that )SAVE is called before Export to ensure the latest session changes are captured.
• Inspect .dyalog files for critical namespaces to ensure no binary data is present.

Diagnostic Detail

Are there any ⎕WC GUI namespaces or ⎕NA external functions that must stay in the workspace? If so, a single-root migration is insufficient, and you must adopt the split-root strategy mentioned above.