Skip to content

Derive project identity from package version and compiler revisions #94

Description

@ScriptedAlchemy

Summary

Stop requiring application authors to repeat the package version in
agent-bundle.config.ts and runtime registries. Derive release identity from
the project package, preserve Agent Bundle's existing source/config/model
revisions, and expose those distinct axes consistently in manifests, dev
status, runtime requests, and provenance.

This is a focused identity migration, not part of filesystem route discovery.

Problem

Agent Bundle currently requires plugin.version in config, while examples may
also restate name/version inside runtime application registries. At the same
time, ProjectContext already records source revision, config digest, model
digest, and source inputs. A static version in multiple authoring surfaces can
drift, while replacing semantic version with a development hash would conflate
release and source identity.

Contract

Reuse and extend the existing ProjectContext; do not introduce a parallel
identity object.

interface ProjectIdentity {
  packageName: string;
  packageVersion: string;
  sourceRevision: string;
  configDigest: string;
  modelDigest: string;
}

Rules:

  • package.json name/version are authoritative for packaged projects;
  • release artifacts and host manifests retain the semantic package version;
  • development status and generated manifests also expose the canonical source
    revision;
  • config/model digests remain separate compatibility/provenance axes;
  • a display label may render
    <packageVersion>+dev.<short-source-revision> without changing the canonical
    semantic version;
  • changing package.json invalidates the project context and source revision;
  • runtime registries and route modules never restate project identity;
  • release builds fail closed when package identity is missing or invalid;
  • a documented development-only fallback may exist for unpackaged scratch
    projects, but it cannot produce a release artifact.

Migration

  1. Read and validate package identity during project loading.
  2. Add derived identity to normalized config and generated manifests.
  3. Warn when plugin.version differs from package.json.
  4. Make plugin.version optional and prefer package identity.
  5. Remove duplicated runtime application identity during route migration.
  6. Deprecate and later remove plugin.version through the repository's normal
    breaking-change policy; this issue does not promise a fixed compatibility
    window.

Acceptance criteria

  • One packaged project declares its version only in package.json.
  • Build, inspect, Workbench, runtime context, and host manifests agree on
    package version, source revision, config digest, and model digest.
  • Editing source changes source revision without changing package version.
  • Editing package version changes package and source identity deterministically.
  • A conflicting legacy plugin.version fails or warns according to the active
    migration phase; it never silently wins.
  • A release build without valid package identity fails closed.
  • No application route or runtime registry repeats name/version.

Design references

Stack position

  • Can land independently of filesystem routes after current project loading.
  • #93 filesystem routes and #95 request context consume its derived identity when available but do not block initial implementation on the migration.

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 requestmeta-frameworkAgent Bundle compiler-coupled meta-frameworkruntimeRuntime context, state, rendering, or execution

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions