veratown-prototype

Runtime Naming Cleanup — Implementation Plan

Status: Plan only. No runtime code, MongoDB data, Railway configuration, or BC account settings are changed by this document.

Goal

Remove prototype from active application identifiers, user-facing runtime text, environment/database configuration, and runtime-owned MongoDB collection names so a production deployment does not carry temporary-development naming. Keep the existing production/test isolation guarantees and preserve data across the eventual rename.

Explicit scope and exclusions

Included:

• Runtime and test TypeScript identifiers, user-facing status command/text, environment examples, database guards, MongoDB collection names, scripts, tests, and active setup/feature documentation.
• A dry-run-first, explicitly applied migration path for existing isolated test and production data.
• An inventory and cleanup of active “prototype” references, including configuration, source, scripts, tests, and docs, subject to the exclusions below.

Explicitly unchanged:

• GitHub repository Rarsus/veratown-prototype, repository URLs/links, and Railway’s repository connection.
• The package name veratown-runtime-prototype in package.json.
• The legacy source database ropeybot, its read-only role, and the existing legacy Veratown configuration collection names copied from it. They are source data contracts, not names for the bot’s new runtime database.
• BC protocol names, Veratown product/feature names, and the RUNTIME_TARGET values production and test.
• Unrelated existing worktree changes.

Do not run a real database migration, deploy, modify Railway variables, or change credentials/account settings as part of code implementation. Those are separate operator actions, gated as described below.

Adopted naming map

Use these names consistently in code, .env.example, active documentation, and migration code. Do not add a compatibility fallback that silently accepts old database names.

Purpose	Current name	New name
Production runtime database	veratown_prototype	veratown
Test runtime database	veratown_prototype_test	veratown_test
Action journal collection	prototypeActions	botActions
Runtime heartbeat collection	prototypeRuntime	botRuntime
Optional door-debug collection	prototypeDoorDebug	botDoorDebug
Appearance itemsets collection	prototypeItemSets	veratownItemSets
Bunny member-state collection	prototypeBunnyStates	veratownBunnyStates
Status commands	!prototype, /bot prototype	!status, /bot status
Default status reply	Veratown prototype is online.	Veratown bot is online.

Database names must be confirmed unused or otherwise explicitly approved for this runtime during migration preflight. If either destination is already in use by unrelated data, stop before any database writes and ask for a different approved name. Do not weaken the fixed target-to-database mapping to work around a collision.

Remove the old status command rather than retaining a prototype alias. Help, command tests, status docs, and examples must present only status.

Inventory and ownership boundaries

Before implementation, search the full repository for prototype and classify each match as one of:

1. Active runtime/code/test/config/database naming to replace.
2. Repository, package, URL, or Railway source identity explicitly excluded.
3. Historical context that is not active configuration or behavior.

Implementation must eliminate category 1 references from active runtime behavior and configuration. Old database and collection names may remain only in the tested legacy-to-new migration mapping and documentation explaining that migration. Leave category 2 unchanged. Update active category 3 documentation where doing so makes setup and production behavior clearer; do not rewrite historical material merely to erase a word when it accurately describes past work.

Use the live code as the authoritative inventory of runtime-owned collections. Expected renamed collections are listed in the table above. Existing Veratown room/map/location/keypad configuration collections retain their names so the legacy config-copy allowlist remains a one-to-one contract. The runtime migration must not copy the source ropeybot database or widen that copy-script allowlist.

Implementation sequence

1. Preflight and complete reference inventory

• Start from a clean, synced implementation branch. Report unrelated worktree changes and do not stage or modify them.
• Re-run repository-wide searches for case-insensitive prototype, Prototype, veratown_prototype, and each old collection name across source, tests, scripts, package/config files, and docs.
• Inspect every Mongo repository, adapter, script, test fixture, index name, error message, and operational document found by the search. Search results are inventory, not permission to rename a legacy source contract.
• Confirm old-to-new mapping, owning modules, retention rules, and all old and new collection/index names are represented in this plan before coding.

2. Rename application and user-facing identifiers

• Rename runtime config and database adapter exported types/functions from Prototype* / connectPrototypeDatabase to neutral runtime names. Update every import and caller, including operator/qualification scripts.
• Rename the database constants and preserve an exhaustive fixed mapping: production → veratown; test → veratown_test. Continue rejecting arbitrary names and the legacy source database.
• Rename the status plugin/command-suite symbols to neutral status names; register only !status and /bot status; update help text and reply text.
• Replace prototype wording in safe defaults, diagnostics, logs, test usernames/fixtures, and script-local temporary identifiers where they represent this runtime rather than an excluded repository/package identity.
• Keep public API type safety, static composition, one Mongo client, and existing plugin lifecycle/command registration behavior.

3. Rename runtime-owned collections and indexes

• Update each collection owner and all direct consumers to use the new names in the table. This includes runtime repositories, heartbeat and debug adapters, Bunny/appearance repositories, qualification scripts, migration tooling, and tests.
• Rename generated/explicit index names that include an old collection name. Preserve index keys, uniqueness, TTL duration, retention timestamps, query behavior, and initialization order.
• Keep legacy Veratown configuration collection names and copy-script allowlist unchanged. Do not use a broad string replacement for collection names.
• Centralize names only where consistent with the current repository’s patterns; avoid introducing a collection registry abstraction solely for this rename.

4. Implement a safe data migration tool

Provide an operator script for moving data from the current test/production databases and old collection names to their new counterparts. It must:

• Be dry-run by default and require an explicit --apply for every write.
• Require an explicit RUNTIME_TARGET; derive both source and destination names from the fixed mapping instead of accepting arbitrary database names.
• Print the selected target, source/destination database names, exact collection mapping, source/destination counts, and required index plan without printing document contents, credentials, chat, access codes, or appearance payloads.
• Use a fixed allowlist of runtime-owned collections. Include the existing application configuration collections that must remain available to the runtime, preserving their names; do not copy unknown collections, profiles, sessions, audit history, or data from ropeybot.
• Validate source documents and destination identity conflicts before writing. Preserve _id and document contents. Do not silently overwrite a destination document that conflicts with a source document; report the conflict and stop.
• Copy in bounded batches using typed collections and safe MongoDB operations. Check write results and return a failing exit status on partial failure.
• Recreate/verify the indexes required by runtime initialization, including botRuntime.expiresAt TTL behavior and the current retention period.
• Be repeatable after an interrupted run, report enough progress to resume safely, and verify post-copy counts and identities before declaring completion.
• Never delete old collections or old databases. Provide a separate, documented manual retirement step only after the new runtime has been independently verified and the operator has approved retirement.

Do not implement dual writes or automatic old-database fallback. Keep the runtime pointed at exactly one fixed database per target. If the migration cannot safely resolve an unknown collection, document shape, duplicate _id, index conflict, or destination collision, fail closed and request operator input rather than guessing.

5. Update configuration, docs, and operational procedures

Update together:

• .env.example and config defaults/examples.
• README setup, feature, status-command, isolation, and collection references.
• docs/operations/RUNTIME_ENVIRONMENTS.md, docs/architecture/BOT-ARCHITECTURE.md, the status feature guide, Bunny/appearance guides where they name the collections, Railway deployment instructions, and any affected script instructions.
• The collection ownership/retention table and runtime status/command diagrams.
• Tests and scripts that assert literal database names, collection names, index names, or status input/reply text.

Document the migration as an operator-led, dry-run-first procedure. Make clear that deploying code which expects the new database before migrating/seeding that target will not find the old data. Update target variables only during an approved deployment cutover.

6. Validate and report

• Add regression tests for the fixed new database mapping; rejection of old, arbitrary, cross-target, and source database names; all renamed collection owners; status command behavior; and migration dry-run/apply/conflict/ interruption/index verification paths.
• Tests use node:test, node:assert/strict, and in-memory fakes. Never use a live BC server, real credentials, or live MongoDB in unit/integration tests.
• Ensure every new test file is explicitly included in the test script in package.json.
• Run the complete required gates after the cohesive implementation: npm run lint, npm run format:check, npm run check, npm test, and npm run build because runtime source and public APIs change.
• Run focused repository-wide searches and verify the only remaining application-level matches are the explicitly excluded repository/package identities or accurate historical records. There must be no old database names or old runtime collection names in active code/configuration.
• Update this plan’s status only after code, tests, docs, and build pass. Report migration dry-run results separately; do not claim a live migration or production cutover unless an operator performed and verified it.

Safety and stop conditions

Stop without applying data changes and request operator direction if:

• Either proposed destination database is occupied by unrelated data.
• Source/destination document counts, _id sets, schema validation, or indexes disagree in a way the migration cannot safely resolve.
• A destination document would be overwritten or an unknown collection would need to be copied.
• The selected runtime target does not map exactly to its fixed database.
• Production migration or deployment approval has not been given.
• The implementation would require weakening the source read-only rule, database-isolation guards, one-journal-owner invariant, retention, or error-reporting requirements.

The MongoDB schema-design skill’s migration/versioning guidance and action policy apply to the implementation. It may be used to design/read-verify the migration, but no live MongoDB write, rename, drop, or deployment action is authorized by this plan alone.

Required repository instructions and workflow

During implementation, read and follow the applicable instructions before editing:

• MongoDB instructions for adapters, repositories, migrations, and scripts.
• Feature instructions for config, composition root, status feature, and command behavior.
• Testing instructions for test structure, fakes, and script registration.
• Git workflow instructions for syncing, branch/PR requirements, validation, commit, and push.
• Authoritative docs listed in README.md, especially runtime isolation, architecture, feature/status, and affected persistence guides.

Use the repository’s built-in node:test tooling. Do not add dependencies. Changes to database isolation guards or scripts require a short-lived implementation branch and a pull request. Commit only the cohesive, validated implementation files; never include unrelated worktree changes, secrets, generated dist/, or database exports.

Definition of done

• Production/test database names and target guards use only veratown and veratown_test.
• No active runtime source, environment example, or ordinary operator script relies on prototype database/collection/type/command naming. Old database and collection names appear only in the tested migration mapping and migration instructions; the old command is not accepted as an alias (a negative compatibility test may name it explicitly).
• Runtime-owned MongoDB collection and relevant index names use the adopted neutral names; legacy source-copy collection contracts are unchanged.
• Status is available only as !status and /bot status, with no prototype-named alias or reply.
• Migration tooling is dry-run-first, explicit-apply, allowlisted, validated, repeatable, non-destructive, and tested.
• Active docs, config examples, and operator rollout steps agree with runtime behavior.
• Lint, formatting, type-check, tests, and build all pass.
• No live data migration, production cutover, or retirement of old data is represented as complete without separate operator approval and verification.