enterprise-pinned-registry

Enterprise Pinned Registry

A lockfile concept for AI generation. Model versions, prompts, brand tokens, and seeds are pinned to a manifest that regenerates the same campaign identically six months, a year, or three years later. Built for enterprises that need reproducibility for legal holds, brand-campaign continuity, regulatory defense, and year-over-year comparability.

When to Use

• Multi-team deployment: 20+ designers / PMs / agencies generating on the same brand, need identical output across all of them
• Year-over-year campaign (annual report, quarterly earnings graphics) must match the prior year's look exactly
• Regulated industry where "reproducible" is a compliance requirement, not a preference
• Legal hold — a specific asset may need to be regenerated identically for litigation support
• Model-provider change management — new versions ship weekly; you want explicit, reviewed upgrades, not drift
• Audit trail: every shipped asset must trace back to a specific model version + prompt + brand token set

Do not use for: one-off exploration, draft/ideation phases, consumer projects.

Prerequisites

Before authoring the registry:

1. Scope — which models, prompts, and brand tokens are in scope? Start narrow (heroes only) then expand.
2. Bump cadence — quarterly? On-demand only? Who approves a bump?
3. Regression-test corpus — what's the set of prompts that must be re-run before a bump is approved? (Typically 10–20 representative prompts.)
4. Storage — registry in the campaign repo, a dedicated brand-registry repo, or a central governance repo?
5. Rollback plan — if a bump produces unacceptable drift, how do we revert? (Git revert is usually enough if the registry is in git.)
6. Audit retention — how long must the registry + generated outputs be retained? 7 years for SOX-adjacent, 10 for pharma, indefinite for trademark defense.

How to Run

Five steps. The registry is the contract; everything generates against it.

1. Author registry.json — model aliases, prompt templates, brand tokens, default params. Each alias pins to an explicit model@version.
2. Fingerprint prompts — every prompt template gets a SHA256 hash stored alongside it. If the prompt string changes, the fingerprint changes, and that's a versioned bump.
3. Configure the CLI — gen-ai config set registry <path> points every call on this machine at the registry. Teams commit the registry to git and sync via clone/pull.
4. Generate against aliases — designers use flux (alias), never flux-2-pro@2.1.3 (raw). Alias resolution is the registry's job.
5. Bump quarterly — run the regression corpus against a candidate new version, diff the outputs, get approval, bump the registry, tag the release (brand-registry-v2026.2).

Quick Reference

The registry itself is the manifest. Commit it. Tag it. Diff it on every bump.

{
  "registry_version": "2026.2.0",

Every generated asset's results.json entry should carry registry_version so reproduction is one command away.

Quick Reference

The registry pins them; it doesn't choose them. For picking, see the per-workflow skills. Typical enterprise registry contents:

Confirm commercial-use + regional availability at bump time with gen-ai models info <id>. Provider terms change; pin is not a license.

Procedure

• Aliases everywhere, raw IDs nowhere. Designers should never see flux-2-pro@2.1.3 in a prompt — only flux.
• The registry lives in git. Commit, tag, diff, review, revert. Full audit trail for free.
• Regression corpus before every bump. 10–20 canonical prompts, run against old and new, visual diff approved by brand lead.
• Pin seeds for reproducibility where the model supports it. --seed 42 reruns the same output deterministically.
• Fingerprint prompt templates. Any string change to a template is a versioned bump, not a silent edit.
• Tag registry versions semver-like (2026.2.0 = year-quarter-patch). Patch for typo fixes; minor for new aliases; major for model swaps.
• Deprecate, don't delete. Removing an alias breaks historical reruns. Mark as deprecated, keep the pin, flag in CLI output.
• Document the bump. Every version bump ships with a changelog: which model, why, regression results, approver.
• Re-run a prior campaign from its registry version quarterly to verify reproducibility still works. If it breaks, the provider deprecated the version — plan migration.

Pitfalls

• Aliases + raw IDs mixed in manifests — teams drift off the registry unintentionally. Lint for raw IDs in PRs.
• No regression corpus — bumps ship, drift is invisible until a comms leader notices a year later.
• Provider deprecates a pinned version — eventually happens. Run your registry's prior versions quarterly to catch this before a legal reroll is needed.
• Prompt edits without fingerprint bump — someone "fixes a typo" in a template, now the output differs. Fingerprint + bump.
• Seed not pinned — reproducibility is partial without it. Set a registry default seed.
• Registry in a personal repo — loses institutional access. Must live in a governance-owned repo.

Verification

Run gen-ai whoami to confirm authentication, then re-run the failed command with --debug.

Commands

Every manifest references aliases, never raw model IDs. The registry is the one place that maps alias → version.

Cost & time

Registry operations are cheap. The value is in what they prevent.

Cost savings scale with team size: a 20-person design team bumping incidentally costs far more in drift than one quarterly reviewed bump.

See also

• enterprise-brand-governor — brand.md gating; pairs with the registry for full policy-as-code
• product-photo-studio — batch catalog runs (reshoot mode); use registry aliases
• enterprise-press-batch — embargo-aware pipeline, pin for year-over-year consistency
• gen-ai-use — CLI reference