promptkit/docs/roadmap/profile-policy.md

Built-In Profile Compatibility Policy

Status

Accepted for implementation on 2026-09-22. The implementation sequence and completion status are maintained in the profile-policy implementation plan. Current code, GoDoc, durable documentation, published module contracts, and release tags remain authoritative until each corresponding implementation change lands.

Prerequisite And Sequencing

Implementation of this roadmap must begin only after the public facade refactor is complete and its compatibility and validation criteria have passed. The refactor preserves existing behavior; this subsequent work introduces the deliberate profile-policy changes.

Profile-source composition, maintained-profile construction, and catalog dependency assembly must use the internal owners established by that refactor. Both scopes may ship in v0.10.0, but they remain separately reviewable changes. This prerequisite has been satisfied. The remaining work proceeds through the profile-policy implementation plan.

Purpose

Define a truthful compatibility and release boundary for Promptkit's maintained built-in profiles. The intended direction is to permit exceptionally rapid catalog updates without weakening Promptkit's stability commitments for its engine, public Go API, configuration semantics, backend registry, or other non-profile behavior.

Model catalogs change faster than the Promptkit runtime. Providers control their own model catalogs and service lifecycles. Promptkit cannot reasonably guarantee that a maintained profile's upstream model or endpoint will remain available, and retaining obsolete profiles can be actively misleading when their targets no longer provide the expected service.

The release model should treat external catalog profiles as volatile data, while providing a small set of Promptkit-owned aliases with stable IDs for applications that prefer a maintained general-purpose selection.

Proposed Compatibility Boundary

The provisional policy would exclude external catalog profile data from Promptkit's cross-version compatibility surface. A catalog or Promptkit release could, without deprecation or advance notice:

• add or remove an external catalog profile;
• rename a profile, represented as removing one ID and adding another;
• change the upstream model selected by a profile;
• change profile defaults such as reasoning effort, timeout, service tier, sampling controls, token limits, or extra parameters; and
• correct or otherwise revise profile metadata in response to upstream behavior.

Promptkit would make no cross-version promise about the continued presence, identity, settings, suitability, or upstream availability of an external catalog profile. The separately defined Promptkit-owned alias IDs would have the continuity guarantee below. Promptkit would make no claim that an upstream provider will continue to serve a cataloged model or endpoint for the lifetime of a Promptkit or catalog release.

This volatility exception should apply only to external catalog profile data. It should not silently weaken the ordinary compatibility rules for:

• Promptkit's exported Go API and GoDoc contracts;
• prompt, profile, and schema format semantics;
• request preparation, execution, validation, repair, cancellation, error, credential, ownership, and concurrency behavior;
• public built-in backend IDs and registry behavior;
• the external catalog packages' exported Go API;
• the catalog manifest and asset schema understood by Promptkit; or
• consumer-defined profiles and backends.

Backend definitions, including endpoint, credential-environment, and capacity metadata, remain outside the profile-volatility exception and subject to the ordinary compatibility policy.

Proposed Stable Promptkit Profiles

Promptkit would maintain a small, explicitly documented set of built-in profiles using existing profile definitions and inheritance:

Stable profile ID	Initial definition	Initial purpose
promptkit-openrouter-standard	Inherits from external catalog profile gemini-flash-latest.	A maintained selection for general-purpose text generation.
promptkit-openrouter-auto	Selects backend openrouter and model openrouter/auto.	Delegates model selection to OpenRouter's automatic routing.

These definitions and purposes describe the initial selections only and are not continuing model-selection promises.

The auto profile can initially be a direct profile definition; it does not require a second catalog alias or a new public API. It inherits connection and credential metadata from the OpenRouter backend and need not add generation overrides. Promptkit forwards openrouter/auto as the model identifier through its ordinary client. OpenRouter owns the routing decision, eligible models, and resulting provider behavior. Promptkit adds no model-selection algorithm or fallback loop. Its ordinary local validation does not check the upstream availability of openrouter/auto.

Both profiles receive the stable-ID guarantee below. References to aliases describe inherited definitions where applicable; the same namespace, precedence, and structural-validation requirements cover direct definitions. Only these two profiles are in scope. This roadmap imposes no additional approval process for future profiles.

The only profile-specific continuity promise is that the literal names promptkit-openrouter-standard and promptkit-openrouter-auto remain available, subject to the supported dependency and consumer-override scope below. Their actual models may change at any time, for any reason, without notice to anyone. No deprecation, approval, or change-announcement gate applies to model selection. The names do not promise a permanent model, provider, routing strategy, or set of defaults. Both initially use OpenRouter, but the profile names themselves are the only continuity guarantee.

In particular, promptkit-openrouter-auto is not required to retain openrouter/auto or automatic routing indefinitely. Neither profile guarantees unchanged output, cost, latency, capabilities, or upstream availability. While using upstream automatic routing, the selected model can vary between requests even with unchanged Promptkit and catalog versions.

Catalog dependency updates must preserve local resolution of the two maintained profile names. If a referenced catalog profile disappears or is renamed, adjust the affected alias together with the dependency update and ship both in the same Promptkit release. If the catalog retains the referenced ID but changes its model, inheritance picks up the change automatically; no separate model-selection approval is required. Ordinary code review and structural validation apply. Upstream deprecation, retirement, and mapping accuracy remain the catalog library's responsibility and do not create a Promptkit monitoring or upstream-verification obligation.

Release validation must prove that every maintained alias resolves against the selected catalog versions. This continuity guarantee applies to the versions selected and tested by Promptkit and assumes consumers have not overridden the alias or its base with their own definitions. Independently upgrading a transitive catalog can remove an alias's base without updating Promptkit; that untested combination is outside the guarantee.

Aliases would retain the ordinary profile precedence and inheritance semantics. They would introduce no new public API or automatic model failover. An already deployed application would retain its compiled alias and catalog data until upgraded; an upstream withdrawal would not change its selection automatically.

Adding these profiles does not change existing default-profile selection. Consumers opt into them through the existing profile-selection mechanisms.

Ownership, Precedence, And Composition

The maintained alias definitions belong to a small Promptkit-owned profile source. Profile precedence is consumer sources in their existing order, then Promptkit-owned aliases, then external catalog profiles. Consumers may override an alias or its base using the ordinary profile mechanisms.

Reserve the promptkit- profile-ID prefix against definitions in external catalogs. Reject such catalog definitions even if they do not yet collide with an existing alias. This namespace rule does not prohibit consumer overrides.

Retain existing catalog-local inheritance and backend-ownership validation, and verify that the combined maintained profiles resolve without relying on consumer overrides. Do not assert a permanent model or routing selection based on a profile name. Runtime inheritance must continue to observe the complete source hierarchy, including consumer overrides of aliases and their bases. Reuse the existing resolver; exact private assembly and validation sequencing belongs in the implementation plan. Do not introduce a second inheritance implementation or freeze alias values in a way that bypasses consumer overrides.

Local Validation And Existing Safeguards

Profile volatility does not remove existing structural validation or library safeguards. Preserve the following implemented responsibilities without making them additional profile-availability or permanent implementation promises:

• catalog assets are immutable build inputs rather than runtime downloads;
• manifests and profiles satisfy the supported schemas;
• IDs are unique and profiles select their owning backend;
• external catalogs do not define IDs in the reserved promptkit- namespace;
• secret-bearing fields and prohibited connection metadata are rejected;
• profile values are normalized, copied, resolved, and overlaid through the existing Promptkit architecture;
• the selected catalogs pass Promptkit's integration suite before a Promptkit release adopts them; and
• the module graph and checksums provide a reproducible identity for the data that was tested.

These checks establish local integrity for selected data, together with the maintained-profile resolution requirement above. They do not establish external catalog profile continuity across versions or live upstream availability.

Promptkit's checks cover local syntax and structural semantics: supported fields, duplicate IDs, namespace conflicts, inheritance resolution, backend references, endpoint URL format, and existing security and value constraints. They expressly exclude attempts to verify that an endpoint exists, a model ID is recognized upstream, or a provider serves that model. Catalog libraries own the accuracy of upstream model and endpoint mappings. Promptkit must not add network probes, model-list lookups, or paid inference checks to catalog adoption or release validation. Ordinary execution continues to report upstream errors through the existing generation-error contract.

Provisional Release Model

The first release adopting this policy should be a new Promptkit minor release because it changes a previously documented consumer expectation and may remove profile IDs on which deployed configuration depends. v0.10.0 is the current candidate.

The OpenRouter catalog's published v1.0.0 contract promised stable profile IDs and advance handling before removal. A later README cannot retroactively weaken that promise. The current recommendation is therefore to establish the new boundary in promptkit-backend-openrouter major version 2, using the dated release convention below, even if its exported Go declarations and manifest schema do not change.

After that boundary is established, maintained catalog releases could publish profile additions, deletions, and modifications rapidly under their documented volatile-data policy. Promptkit could select a reviewed catalog update without treating profile churn as a compatibility break in its otherwise stable core. Later catalog updates and corresponding alias adjustments may ship in a Promptkit patch release, such as v0.10.1 after v0.10.0, provided unrelated compatibility contracts remain intact. Profile churn alone does not require v0.11.0 or another minor release.

Promptkit's integration validation covers the catalog versions it selected and tested. It does not guarantee upstream correctness for those versions. Go module version selection may cause an advanced consumer's build to select a newer compatible catalog module than Promptkit's own requirement; the resolved module graph, rather than Promptkit's go.mod alone, determines the actual embedded data.

Release notes may identify selected catalog updates and summarize changes for convenience, but no notice of model-selection changes is required, in advance or afterward. Ordinary release records and validation still apply; they must not introduce a profile-change announcement gate.

Proposed Date-Based Catalog Versions

The proposed catalog version convention is vMAJOR.YYYYMMDD.N. This is a calendar-based convention encoded in Go-compatible semantic-version syntax:

• MAJOR identifies the compatibility generation of the exported Go package and catalog asset format. Profile additions, deletions, renames, and setting changes do not require a major-version increase under the proposed policy.
• YYYYMMDD is the release publication date in UTC. It occupies the numeric minor-version component and communicates snapshot freshness, not the scale or compatibility of a profile change.
• N starts at zero for each UTC date and increments for every additional release that day, regardless of the kind of profile change. It occupies the numeric patch-version component and carries no profile-continuity promise.

For example, v2.20260922.0 and v2.20260922.1 would be successive releases on September 22, 2026, followed by v2.20260923.0 on the next day. These are illustrative dates, not scheduled releases. Use the actual publication date; published versions remain immutable, and corrections receive new versions. Within a major generation, these versions sort chronologically under Go's ordinary module-version ordering.

Go requires a matching major-version suffix in module paths for version 2 and later. The OpenRouter transition would therefore use gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 in the catalog's module declaration and Promptkit's imports and dependency requirement. A first release on the example date would be v2.20260922.0; a preliminary v2.0.0 release is not required. Promptkit consumers would continue importing Promptkit through its existing module path. See the Go module version rules and major-version suffix rules.

Both maintained catalog libraries, OpenRouter and Rakestrawhome, would transition to this policy and dated major-version-2 convention as part of this work, with matching /v2 module paths. Thereafter each would release independently; releases need not share dates or revision numbers. Promptkit itself would retain its existing version-number convention and explicitly select and test individual catalog versions.

This proposal replaces the earlier idea of classifying catalog refreshes as ordinary minor releases and metadata corrections as patches. The date records when a snapshot was published; release notes may summarize what changed. Neither establishes live upstream availability or cross-version profile continuity. The convention remains provisional along with this roadmap.

Consumer Guidance

The eventual durable documentation should make the tradeoff explicit:

• external catalog profiles optimize for convenient access to a maintained current model catalog;
• selecting or inheriting directly from an external catalog profile accepts its volatility;
• selecting either promptkit-openrouter-standard or promptkit-openrouter-auto guarantees only continued availability of that literal profile name within the supported dependency scope; models and settings may change for any reason without notice;
• promptkit-openrouter-auto initially delegates model selection to OpenRouter; its initial routing behavior is not a permanent contract, and upstream routing can change independently of a library upgrade;
• pinning the complete resolved Go module graph preserves the exact catalog assets used by that build, but cannot preserve live upstream availability;
• applications that require their own fixed model selection or settings should define a complete application-owned profile with an explicit backend, model, and defaults; and
• an application-owned alias that inherits from an external catalog profile isolates application configuration from the catalog ID only while that base exists; it deliberately continues to inherit changes to the base profile.

Promptkit should not promise automatic migration or replacement aliases for every removed external catalog ID, deprecation windows for catalog profiles, or runtime fallback from a removed or unavailable model. Its small maintained alias set provides continuity through coordinated library releases.

Expected Documentation And Repository Changes

If accepted, implementation would likely require coordinated changes in Promptkit and each maintained catalog repository:

• revise catalog compatibility and release documentation to distinguish the stable Go/schema boundary from volatile profile data and document the vMAJOR.YYYYMMDD.N convention;
• update Promptkit's release policy with a narrowly scoped built-in-profile volatility exception for external catalogs and an explicit continuity guarantee for Promptkit-owned alias IDs, while retaining its other pre-v1 compatibility rules;
• add promptkit-openrouter-standard through existing profile inheritance and promptkit-openrouter-auto as a direct openrouter/auto profile; document their distinct purposes and opt-in selection;
• require coordinated catalog and alias updates, with release checks proving every maintained alias resolves against the selected catalog versions;
• update the architecture, format, source, development, and consumer documentation at their existing ownership boundaries;
• keep exact external profile inventories in the catalog repositories, linking to the selected versions from Promptkit rather than duplicating their tables; keep Promptkit's small alias inventory and runtime semantics in its own canonical documentation;
• revise tests and compatibility-fixture terminology so they protect local structural validity and maintained-profile resolution, without asserting cross-version stability of external profiles; retain an exact selected-version snapshot only where its review value justifies its maintenance cost;
• publish both revised catalog contracts as dated major-version-2 releases with matching /v2 module paths;
• update Promptkit's catalog imports and requirement, current selected-profile documentation, and release guidance; and
• publish the policy transition and its consumer impact in the eventual Promptkit minor release note and annotated tag.

Implementation is sequenced and tracked in the profile-policy implementation plan.

Non-Goals

This proposal does not introduce:

• runtime catalog downloads, discovery, or mutable global registration;
• any upstream endpoint or model-existence verification by Promptkit, or guarantees based on current provider health;
• automatic replacement aliases or migration tables for every removed catalog profile, or runtime fallback models;
• weakened validation of catalog structure or content;
• weaker compatibility for Promptkit's public engine or consumer-defined configuration; or
• a general exception allowing arbitrary dependency updates to break stable Promptkit behavior.