Addon Update vs Clean Install

Use this page when deciding whether a package is a new addon lineage or an update to an existing governed addon.

Final Intended Rule

system governance classifies clean install versus update.

Installer executes only the classification system governance approves.

Clean Install

A clean install introduces a new governed addon lineage.

It requires:

• new stable `product_uuid`
• stable `addon_key`
• no unsafe addon key collision
• no unsafe slug collision
• no unsafe route path collision
• no unsafe route key collision
• accepted dependencies
• accepted risk declarations
• valid install contract
• valid schema/permissions contracts when declared

Update

An update modifies an existing governed addon lineage.

It should keep:

• the same `product_uuid`
• the same `addon_key`
• stable route keys unless a migration explains the change
• compatible owned table names unless schema migration explains the change

It may change:

• `package_uuid`
• `version`
• display text
• implementation files
• additive schema
• permissions with a migration
• public targets with compatibility notes

Not An Update

A package is not an update merely because it uses the same:

• folder name
• addon key
• route
• slug
• display name

Those are collision signals. system governance must compare lineage truth before approval.

Current Drift

Current Installer code still participates in same-lineage checks and system governance collision validation before deployment. Treat that as transitional execution behavior.

Final docs should say: system governance decides lifecycle meaning; Installer deploys the approved package.

Developer Checklist

Before packaging an update:

• keep `product_uuid` unchanged
• generate a new `package_uuid`
• increment `version`
• list schema migrations
• list permission additions/removals
• preserve existing public routes or document redirects
• test install on a clean environment
• test update over an existing install
• verify system governance reports same lineage
• add a changelog record

Related: Installer/Package Install and Update Flow, Installer/Package Install and Update Flow, Addon Development/Route and Slug Collision Handling.