veratown-prototype

ABDL Bot as a Separate Veratown Runtime

Status: Superseded by supervisor-managed ABCL Date: 2026-10-29 Related: ABDL bot Veratown adapter proposal, Bot runtime architecture, Helper Bots, Railway helper deployment guide

The original separate-runtime proposal is retained as decision history. The implemented deployment uses the supervisor for ABCL coordination and a separate ABCL-capable helper for observation and assigned work; see the current ABCL feature guide.

Executive summary

Port the approved abdl-bot behavior into a Veratown-native feature and run it as a separate Veratown service with a dedicated BC account. The new runtime role uses Veratown’s existing BcClient, BC protocol types, action journal, location model, and lifecycle; it does not embed bc-bot, create a proxy facade, or add a second socket to the supervisor process.

The existing supervisor remains deployed and unchanged at runtime. ABCL is disabled by default, starts only in its dedicated runtime role, and may act only for eligible, consenting participants while the target’s current server-observed position is inside the configured region.

This is a behavior port, not a byte-for-byte import. The upstream project can remain untouched, but reproducing or adapting its code still requires appropriate permission. The inspected upstream tree at commit 7cd49dd1bae8d5537e9bdd3a5ff6cf869ec1045c did not contain a LICENSE file. Confirm a compatible license or written permission before copying/adapting source. Without permission, implement from independently authored behavior requirements.

Goals

• Keep the Veratown supervisor’s process, BC account, and rate-limited socket independent from ABCL work.
• Use Veratown’s BC adapter and action contracts in the ABCL service.
• Require region, participant consent, and feature policy checks at dispatch time for every side effect.
• Preserve explicit lifecycle, journaling, validated state, and safe rollback.
• Track the upstream behavior revision and provide a repeatable, review-led process for porting upstream changes.

Non-goals

• Load the upstream bot’s src/index.ts, API_Connector, or bc-bot package.
• Create an HTTP, Socket.IO, or API-compatible proxy between two bot runtimes.
• Share the supervisor’s BC credentials or use its account for ABCL.
• Treat a database journal, a position request, or an entry event as proof of current BC state.
• Automatically import future upstream changes or enable all upstream behavior without a separate policy review.

Proposed runtime architecture

Add a statically composed ABCL runtime mode to the existing Veratown application:

Veratown Supervisor service                 ABCL service
  dedicated BC account                        dedicated BC account
  one BcClient + local send queue              one BcClient + local send queue
  existing supervisor plug-ins                ABCL-only plug-in set
  existing runtime database target             same fixed target mapping
                 \                              /
                  +---- shared BC room --------+
                               |
                 target characters/map positions
                               |
                room-scoped ABCL configuration

The ABCL service is a separate process and Railway service, built from the Veratown repository. It uses one Veratown BcClient, one ActionCoordinator, and the normal database isolation rules. It does not import or instantiate the supervisor runtime. Each process owns its own socket and rate limiter; no process owns a second connection.

Introduce an explicit validated runtime role, preferably a discriminated configuration value such as RUNTIME_ROLE=supervisor|helper|abcl, instead of inferring the role from multiple unrelated booleans. The existing supervisor remains the default. The ABCL role statically composes the required shared infrastructure and only the ABCL plug-in; it does not start commands, games, helper task management, or supervisor feature handlers unless separately approved. Update config.ts, PrototypeConfig, .env.example, setup docs, startup diagnostics, heartbeat/runtime identity, and tests together.

The ABCL runtime receives its own dedicated BC credentials and a stable ABCL_AGENT_ID. It must use the same RUNTIME_TARGET, fixed database mapping, BC_ROOM, and room/location configuration as the supervisor. Store no credentials in MongoDB. ABCL-specific state, if needed, belongs in a dedicated, validated collection in the already selected runtime database; it must not use the legacy source database.

Feature responsibilities

Create src/features/abcl/ as a Veratown feature with:

• A statically registered AbclFeaturePlugin and a narrowly scoped service.
• Zod-validated room policy, consent/eligibility state, and any persisted ABCL model.
• Typed subscriptions to required BC message and character observations.
• Dedicated journaled actions for each supported state-changing operation.
• A region policy that resolves the configured location key against current server-observed map state.
• A cancellable scheduler for recurring work; no free-running unhandled loop.
• Structured, redacted failure reporting and safe stop/drain behavior.

Do not expose a generic sendPacket or mutable BC character object to feature logic. Reuse existing Veratown communication and appearance services where their semantics fit. Add an adapter-level dedicated action only for a protocol operation that is supported by the pinned BC types and cannot be expressed by an existing typed action. Do not nest BcApiPlane.dispatch() in an already-journaled action.

The behavior port is explicitly reviewed for scope. Upstream room-wide triggers, automatic target selection, appearance mutations, and mod-specific Hidden messages are not enabled merely because they exist upstream. Each is implemented only after its protocol contract, consent policy, target rules, and observability are defined.

Region, consent, and concurrency rules

The ABCL configuration identifies one enabled region by stable location key. Before every action—including work initiated by chat, Hidden messages, timers, or retries—the service must validate:

1. The sender and payload are valid and within size limits.
2. The feature is enabled for the current room/runtime.
3. The affected participant is eligible and has explicitly opted in.
4. The participant’s latest fresh BC-observed position is inside the configured region.
5. Any required operator, room-admin, or allowlist policy is satisfied.
6. The target and desired state still match immediately before dispatch.

Location entry/exit events help start or cancel work, but do not alone authorize an action: the participant may have left before a timer fires. On exit, disconnect, stale observations, configuration changes, or plug-in stop, cancel pending work and do not dispatch. Unknown consent, stale position, malformed state, and unavailable BC evidence all fail closed.

The separate service isolates socket queues and process failures, but it does not isolate the shared BC room or serialize mutations against the supervisor. The current action coordinator’s in-process sequencing is not a cross-process lock. Before enabling ABCL mutations to another character, the design must provide one of these reviewed protections:

• A shared, room/member-scoped mutation lease used by ABCL and every other Veratown process that can mutate that character; or
• A narrower operation policy that proves the ABCL action cannot race with any other enabled mutation path, with an explicit reject/reconcile behavior.

Do not treat the journal as a lock. If cross-process conflict protection is not implemented, keep potentially conflicting appearance mutations disabled.

Upstream change tracking

The port should record the source and behavior lineage without creating a runtime dependency:

• Maintain src/features/abcl/UPSTREAM.md with repository URL, exact upstream commit, reviewed date, permission/license reference, and a mapping from upstream behavior modules to Veratown modules/tests.
• Review upstream changes by comparing an explicit commit range; never track main implicitly.
• For each upstream change, decide whether it is in scope, update the Veratown behavior port and tests manually, and record accepted, deferred, or rejected items in the lineage note.
• Do not overwrite Veratown code with upstream files or run an automatic source-copy script. The objective is to port behavior through native contracts, not to preserve source-level API compatibility.
• Re-run license/permission review if source files, content, or the upstream license changes.

If periodic updates become frequent, a read-only comparison script may report the upstream commit range and changed paths. It must not import code or create a change automatically. Every behavior update remains a normal reviewed implementation with adapter, tests, and docs updated together.

Configuration and deployment

Configuration is room-scoped and disabled by default. It should include:

• enabled and an explicit schema version.
• The target room key and enabled region location key.
• Participant consent/eligibility policy and operator-managed allowlist rules.
• Bounded scheduler/action budgets and message-size limits.
• Any retention and data-minimization policy for ABCL mod state.

The RUNTIME_ROLE=abcl service uses the same fixed production or test database selection as other Veratown runtimes. Deploy and qualify against veratown_prototype_test first with dedicated non-production BC accounts. Production uses a separate ABCL BC account and service; never use the supervisor’s credentials. The ordinary supervisor remains on its current role and deployment.

The operator must see separate heartbeat/runtime identity for the ABCL instance, including its role, room, runtime target, enabled state, and freshness. Secrets and sensitive mod/chat content must not appear in logs, heartbeats, or action metadata. An ABCL deployment must have an explicit disable/rollback procedure that stops its feature before closing its BC client.

Implementation and qualification phases

Phase 0: Policy and feasibility

1. Confirm upstream code/content permission.
2. Select the behaviors to port and the explicit exclusions.
3. Specify participant opt-in, region, administrator controls, and data retention.
4. Inventory all BC writes and identify the correct BC observation for each.
5. Resolve cross-process target-mutation serialization before allowing appearance mutations.

Phase 1: Runtime role and read-only feature

1. Add the validated runtime role and static ABCL composition branch.
2. Add the ABCL plug-in lifecycle, room policy, region observation, heartbeat identity, and read-only event handling.
3. Test that supervisor/helper startup and shutdown order remain unchanged.
4. Verify that ABCL role starts no unrelated feature plug-ins.

Phase 2: Guarded actions

1. Implement only the first approved actions with dedicated Veratown actions.
2. Add action journaling, target/desired-state reconciliation, and cross-process serialization or a reviewed non-conflict restriction.
3. Add tests for dispatch fencing, region exit, stale observations, consent, repeated events, ambiguous outcomes, and cancellation on stop.

Phase 3: Test-room qualification

1. Deploy the ABCL role to a separate test service using RUNTIME_TARGET=test and a dedicated test account.
2. Enable one reviewed region for explicitly consenting test participants.
3. Exercise reconnects, simultaneous feature activity, region exits, action timeouts, process restart, and rollback.
4. Inspect only safe action metadata and observed outcomes; do not capture or retain private account data or full chat/mod payloads.

Phase 4: Production approval

Production activation is a separate operator decision after the test report, policy, data retention, and rollback procedures have been reviewed. The feature remains disabled by default in production configuration.

Required tests

• Runtime-role parsing, invalid role combinations, and fixed database mapping.
• Static composition: ABCL role starts only the approved plug-ins and shares exactly one BcClient/send queue within that process.
• Region geometry and freshness, including leaving between enqueue and dispatch.
• Consent/allowlist rejection before any side effect.
• One test per dedicated action for dispatch, observation, timeout, and reconciliation semantics.
• Timer cancellation, task drain, subscription disposal, and clean stop.
• Cross-process target-mutation lease contention/expiry/recovery, if that design is selected.
• No regression to supervisor/helper composition and shutdown order.

Risks and mitigations

Risk	Mitigation
Independent service mutates state concurrently with supervisor	Require shared target mutation serialization or keep conflicting actions disabled
Region event becomes stale before delayed work executes	Revalidate current BC-observed position immediately before dispatch
ABCL behavior acts on non-consenting room members	Explicit opt-in and fail-closed eligibility on every action path
New role increases operator configuration mistakes	Validated enum, mutually exclusive composition, fixed DB mapping, startup diagnostics, and role-specific docs
Upstream behavior drifts from the port	Pin commits, maintain a behavior mapping, and review updates manually
Source adaptation is not licensed	Confirm permission before copying/adapting; otherwise implement independently
ABCL work destabilizes the existing supervisor	Separate process, account, send queue, deployment, disabled-by-default config, and staged rollout

Acceptance criteria

• The supervisor deployment remains unchanged and continues to own its own single Veratown BcClient.
• The ABCL service is a separate statically composed Veratown runtime with its own account and one BcClient.
• No bc-bot dependency, raw socket access, arbitrary packet proxy, or unjournaled state mutation is introduced.
• Every side effect is disabled by default and guarded by fresh region, consent, permission, and target-state checks.
• Cross-process conflicting mutations are serialized or explicitly disabled.
• ABCL runtime status and failure are distinguishable from supervisor status.
• Test-room qualification, rollback, and upstream lineage records are complete before production activation.