Skip to content

Add safe managed lifecycle for generated host bundles #101

Description

@ScriptedAlchemy

Summary

Move from build-only host artifacts to an optional, receipt-backed lifecycle:
preview, install, update, repair, uninstall, rollback, recovery, and Doctor
verification. Preserve unrelated host configuration and apply component sets
atomically.

Problem

Generating valid plugin directories is insufficient for complex integrations.
Hosts may own shared JSON/TOML registries, require their own CLI installer,
prompt for trust, stage a plugin before activation, or use native extension
directories. Updating one component must not remove another or overwrite
third-party settings.

TraceDecay currently implements these guarantees itself. Agent Bundle should
make them a reusable framework capability after the host component compiler
can describe exact ownership.

Lifecycle

inspect observed state
  -> preview immutable mutation plan
  -> require exact confirmation digest
  -> backup owned/shared documents
  -> apply component transaction
  -> host-specific activation
  -> verify native registration and artifact bytes
  -> publish receipt

Supported operations:

  • install;
  • update;
  • repair;
  • uninstall;
  • rollback to the prior confirmed component set;
  • recover an interrupted journal.

Safety requirements

  • safe, canonical install roots with symlink/path-escape refusal;
  • content digests and ownership markers per artifact;
  • exact preview/apply revision pairing;
  • component-scoped backups and receipts;
  • atomic or journaled multi-file writes;
  • structured merges that preserve unrelated host keys;
  • host CLI registration where the host owns its registry;
  • competing-extension detection;
  • explicit manual-activation state where automation is unavailable;
  • no credentials in manifests, receipts, or logs.

Doctor

Doctor reports each component as installed, missing, repairable, deferred,
conflicted, unavailable, or corrupt. It verifies:

  • artifact content and provenance;
  • native host registration;
  • activation/trust state where observable;
  • protocol/runtime compatibility;
  • receipt and backup integrity;
  • stale or interrupted journal recovery.

Non-goals

  • Claiming installation merely because files were generated.
  • Replacing a shared host configuration wholesale.
  • Remotely distributed third-party bundles without a separate trust model.
  • Automatically trusting hooks or extensions on the user's behalf.

Acceptance criteria

  • Dry run opens no writer and reports exact planned paths and shared-config
    mutations.
  • Install and update preserve unrelated host configuration.
  • An interrupted multi-component install recovers or rolls back safely.
  • Repair restores owned artifacts without adopting foreign paths.
  • Uninstall removes only receipt-owned artifacts and registrations.
  • Doctor distinguishes activation deferred from installed-and-active.
  • At least two materially different host registration mechanisms pass real
    lifecycle tests.

Design references

Stack position

Full meta-framework stack

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthost-integrationAgent host capabilities, projection, discovery, and lifecyclemeta-frameworkAgent Bundle compiler-coupled meta-framework

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions