Versions and activation

TCAF installs each release in its own version directory and keeps an explicit active version. This allows a developer to test or retain multiple runtimes without copying framework files into project repositories.

Version management is separate from project adoption and task execution. Changing the active runtime does not automatically rewrite project documents or migrate a target project.

Show the active framework version

Run:

tcaf version

The text output contains only the active runtime version.

For machine-readable output:

tcaf version --format json

List installed versions

Run:

tcaf versions

The command reports the active version and lists every version directory found in the installation home. The active version is marked with *.

Example:

Active: 0.3.3
  0.3.2
* 0.3.3

For JSON output:

tcaf versions --format json

The result distinguishes:

• whether an installed launcher is being used;
• the active version;
• all discovered installed versions.

Install another version

Run the install.py belonging to the release you want to add:

python install.py

The installer validates that release and copies it under:

<runtime-home>/versions/<version>

Installing a new version also records it as active.

Because every release carries its own registries, manifests, adapters and runtime code, activation switches the complete framework version rather than replacing individual modules selectively.

Activate an installed version

Run:

tcaf activate <version>

Before activation, TCAF verifies that:

• the installed version directory exists;
• it contains a VERSION file;
• framework validation passes for that version.

If validation fails, the version is not activated.

A successful command reports:

Activated TCAF <version>

Then verify the active runtime:

tcaf doctor
tcaf version

Reinstall the same version

The installer refuses to overwrite an existing version by default.

For an intentional reinstall:

python install.py --replace

--replace replaces only the matching version directory and preserves the previous directory temporarily while the copy is completed. It should not be used as a generic recovery command before diagnosing the problem.

Recommended sequence:

tcaf doctor
tcaf versions
python install.py --replace
tcaf doctor

Adapter preference and version activation

The installation home stores active version and adapter preference together. Activating another version changes the version while preserving the other active installation settings.

Always run tcaf doctor after activation because adapter availability and registry behavior belong to the selected release.

Project compatibility

TCAF project documents include the framework version they were prepared against, but project evidence and runtime installation remain separate.

When changing runtime version:

• do not silently rewrite canonical project documents;
• read the release notes or repository diff for changed schemas and procedures;
• run tcaf validate --target <project-path>;
• reconcile project documentation only when the new version requires a real change;
• keep developer edits and current repository state authoritative.

A newer runtime does not automatically make old evidence invalid, and a recent file timestamp does not prove compatibility.

Pre-1.0 caution

TCAF 0.3.3 is a pre-1.0 draft. Until a stable compatibility policy is published, treat version changes as explicit engineering changes rather than transparent package upgrades.

Prefer:

1. installing the new version alongside the current one;
2. validating the new runtime;
3. testing it on a bounded target or workflow;
4. activating it deliberately;
5. retaining the previous validated version until the transition is accepted.

Custom installation homes

If TCAF was installed with a custom --home, version commands work through the launcher created for that installation.

Do not manually edit active.json unless you are repairing the installation with full knowledge of the expected structure. Use tcaf activate so validation occurs before the active version changes.