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
- Read and validate package identity during project loading.
- Add derived identity to normalized config and generated manifests.
- Warn when
plugin.version differs from package.json.
- Make
plugin.version optional and prefer package identity.
- Remove duplicated runtime application identity during route migration.
- 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
Summary
Stop requiring application authors to repeat the package version in
agent-bundle.config.tsand runtime registries. Derive release identity fromthe 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.versionin config, while examples mayalso restate name/version inside runtime application registries. At the same
time,
ProjectContextalready records source revision, config digest, modeldigest, 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 parallelidentity object.
Rules:
package.jsonname/version are authoritative for packaged projects;revision;
<packageVersion>+dev.<short-source-revision>without changing the canonicalsemantic version;
package.jsoninvalidates the project context and source revision;projects, but it cannot produce a release artifact.
Migration
plugin.versiondiffers frompackage.json.plugin.versionoptional and prefer package identity.plugin.versionthrough the repository's normalbreaking-change policy; this issue does not promise a fixed compatibility
window.
Acceptance criteria
package.json.package version, source revision, config digest, and model digest.
plugin.versionfails or warns according to the activemigration phase; it never silently wins.
Design references
ProjectContextrevision and digest modelStack position
Full meta-framework stack