Skip to content

Assembly Migration and Compatibility

Unified Artifact Assembly (UAA) is additive: your existing project templates, composite artifacts, bundles, and deployment sets keep working through their existing routes. This guide explains what UAA can currently translate from those legacy shapes, what it deliberately does not, and what "compatible" means in practice.

Nothing existing is removed or force-migrated

skillmeat scan, skillmeat project-templates/skillmeat composite deploys, bundle installs, and deployment-set materialization are unchanged. There is no destructive migration step, no forced conversion, and no behavior change to any of those legacy read/deploy paths as a result of UAA shipping. Nothing about authoring or using an assembly requires you to convert or retire an existing template, composite, bundle, or deployment set.

What the compatibility adapters translate

Internally, SkillMeat has pure, read-only translation functions (skillmeat.core.assembly.compat) that map two legacy record shapes into the assembly domain model (an AssemblySpec plus one ModuleDefinition per member):

  • Project templates (ProjectTemplate + its TemplateEntity rows) map to managed:template/<id> — one module per template entity, ordered by deploy_order, with each entity's required flag preserved (an optional entity stays optional).
  • Composite artifacts (CompositeArtifact + its CompositeMembership rows) map to managed:composite/<id> — one module per member, ordered by membership position. If a membership has a pinned_version_hash, the translation verifies the pin still matches the member's current content before proceeding.

These translations are pure: they never write files, never mutate the legacy record, and never mint a new source version. The legacy record's own ID is preserved unchanged in the mapping, so anything that already reads or deploys by that legacy ID keeps working during this compatibility window.

What is intentionally not adapted

  • Context modules (memory-selector modules — see Context Modules) are never translatable: they select memory items by criteria at read/materialization time, so they have no static source artifact and no fixed output path — the two properties every assembly module requires. Attempting to translate one reports a clear, structured "not convertible" reason rather than silently producing an incomplete module.
  • Bundles and deployment sets are intentionally out of scope for translation. Both remain what they already are — envelopes/orchestrators that install or materialize other artifacts — not a source of assembly modules. If a bundle or deployment set eventually needs to invoke a resolved assembly as one of its members, that is a distinct, forward-looking integration, not a compatibility mapping.

Fail-closed, not lossy

A legacy record that can't be losslessly represented (a member with no stored content, no path_pattern, an absolute or path-traversal output path, or a version pin that no longer matches current content) is reported as blocked, never as a partial or best-effort mapping. You get a clear reason for every blocked member rather than a silently incomplete assembly.

Rollout: the feature flag

Unified Artifact Assembly is a staged, opt-in rollout, gated by one flag: SKILLMEAT_UNIFIED_ARTIFACT_ASSEMBLY_ENABLED (default off).

  • Flag off (default): the /api/v1/assemblies/* API, the skillmeat assembly CLI, and the Assembly workspace are all unavailable. Every existing template/composite/bundle/deployment-set read and deploy path behaves exactly as it did before UAA existed — this is the zero-risk default for anyone not yet opting in.
  • Flag on (SKILLMEAT_UNIFIED_ARTIFACT_ASSEMBLY_ENABLED=true): the full pipeline in this guide set becomes available — authoring, resolving, previewing, and applying UAA-native definitions (managed/builtin/ user/project assemblies, per Authoring). You do not need any legacy template/composite/bundle to use it once enabled.

Once enabled, the effective-settings layer at GET /api/v1/settings/assembly (or skillmeat config get assembly.*) is a separate, finer-grained governance surface on top of the flag — it narrows what an enabled assembly definition can do (allowed source scopes, module-graph limits, permitted rule actions, allowed target adapters); it does not itself turn the feature on or off. See Editions for the full precedence chain of that layer.

Check the project CHANGELOG.md's [Unreleased]/latest release entry for whether a given legacy deploy path (e.g. deploy_template_async) has also been wired to consume the compatibility adapters automatically in your installed version — that wiring is tracked and rolled out separately from the flag above.

  • Authoring — build a managed/TOML-authored assembly directly, independent of any legacy record.
  • Bundle & Composite Authoring — the existing (unchanged) composite/bundle authoring flow.
  • Editions — where policy ceilings are configured and how they layer.