veratown-prototype

ABDL Bot Integration Through Veratown Adapters

Status: Proposal
Date: 2026-10-29
Related: Bot runtime architecture, BC API plane, BC socket acknowledgements, Helper Bots

Executive summary

Integrate selected abdl-bot behavior as a statically wired Veratown feature, while replacing its direct bc-bot connectivity with a narrow, in-process compatibility facade backed by Veratown’s existing BC client and feature services. The facade is an adapter for the upstream code, not a second socket, network proxy, or general-purpose bc-bot replacement.

The Veratown feature remains the policy and action boundary: it validates inbound data, checks region membership and consent, routes each state change through a dedicated journaled action, and only treats BC-observed state as evidence. The upstream project remains a separately pinned source with a small, explicit integration patch; it is not added as a runtime dependency.

The upstream repository’s current main tree was inspected at commit 7cd49dd1bae8d5537e9bdd3a5ff6cf869ec1045c. The tree did not contain a LICENSE file. Do not copy, vendor, or adapt its copyrighted source until a compatible license or written permission has been confirmed. If permission is unavailable, implement the required behavior independently from public behavior requirements rather than importing source.

Problem and feasibility

abdl-bot currently creates its own bc-bot API_Connector, logs into BC, subscribes to room events, and sends messages and character changes through that API. Its ABCL code also relies on API-specific mutable character objects and a singleton API imported from the application entry point.

Veratown deliberately has a different boundary:

• BcClient is the only Socket.IO owner and the owner of the shared send queue.
• Feature mutations use dedicated actions and ActionCoordinator.
• Room and character snapshots change only from inbound BC updates.
• Features are statically wired in src/app/start.ts; they do not dynamically load external bot packages.

Therefore, replacing only the connector constructor or forwarding arbitrary SendMessage calls would not be a safe or complete integration. A fully transparent bc-bot emulator would need to imitate its broad mutable API and could bypass Veratown’s action, acknowledgement, region, and permission rules. The viable design is a deliberately small compatibility port for the API surface the selected ABCL modules need. The upstream entry point, login, reconnect, room creation, process handlers, and socket ownership are excluded.

Goals

• Reuse selected upstream ABCL rules and content without running its connector.
• Use exactly the existing Veratown BcClient, rate limiter, snapshots, and ActionCoordinator in a Veratown process.
• Restrict behavior to an explicitly configured location region and eligible, consenting participants.
• Keep upstream-origin code distinguishable from Veratown adapter and policy code, making updates attributable and reviewable.
• Keep the feature disabled by default and make shutdown, failure, and rollback independent of unrelated feature behavior.

Non-goals

• Implement the entire bc-bot API or support arbitrary bc-bot applications.
• Run abdl-bot/src/index.ts, create another API_Connector, or open a second socket from the Veratown process.
• Call socket.emit, BcApiPlane.dispatch(), or generic packet dispatch from ABCL domain code.
• Reproduce every upstream behavior automatically. Each behavior is reviewed for protocol support, consent, region policy, and safe action semantics.
• Automatically import or deploy the latest upstream main.

Proposed architecture

Upstream ABCL behavior modules (pinned, reviewed source)
                     |
       narrow ABCL compatibility interface
                     |
      Veratown ABCL adapter + policy services
        |            |             |
  BcClient reads  Location/map   Dedicated journaled
  and events      observations   BC actions/services
        |            |             |
        +------------+-------------+
                     |
          existing BcClient queue
                     |
              BC Socket.IO

Add a feature under src/features/abcl/, with a BotPlugin, domain/service code, validated model/configuration, dedicated actions, and tests. Register it statically in src/app/start.ts. Inject only the collaborators it needs:

• Validated room/character observations and supported event subscriptions.
• MapLocationEventBus and a current observed-location query so the service can enforce a configured location key and exact point/region geometry.
• Existing communication and appearance action services where their contracts match the behavior.
• A dedicated BC adapter action for any supported ABCL-specific Hidden packet or appearance operation not covered by an existing feature API.
• A repository for bounded, validated ABCL state if persistence is required.

The compatibility interface should be purpose-built for these modules, not named or exported as a drop-in API_Connector. Its read side exposes immutable, validated projections and disposable event subscriptions. Its write side accepts typed intents and returns Veratown action outcomes. It must not expose the socket, BcClient internals, arbitrary packet payloads, mutable snapshots, or generic BC write methods.

Compatibility surface

Before implementation, inventory the upstream call sites and specify the smallest method/event contract they actually require. Likely categories are:

Upstream need	Veratown-facing boundary
Current player and room roster	Read-only projections from the current BcClient snapshot
Room messages and character entry	Validated BC event subscriptions with disposers
Chat, emote, whisper, and Hidden messages	Typed communication or dedicated journaled actions, only where supported
Appearance item changes or expressions	Existing guarded appearance services/actions, or new dedicated actions with observed-state reconciliation
ABCL mod data messages	Explicitly validated and size-bounded protocol adapter; no unchecked JSON casts
Timers and recurring work	Feature-owned cancellable scheduler; all work drained or cancelled on stop()

This table is a discovery checklist, not a promise that every upstream method has a safe Veratown equivalent. In particular, upstream methods that appear synchronous but cause asynchronous Veratown actions may require changing the integration seam or call sites to await a typed result. Do not simulate synchronous success.

Region, consent, and action policy

The feature is configured for one stable, operator-managed Veratown location key whose geometry is an enabled region. Region membership is based on server-observed map position, not a requested teleport, cached database value, or the bot’s own assertion.

Every action path must:

1. Validate the incoming message, sender, payload size, and protocol shape.
2. Resolve the participant’s current BC-observed character and region state.
3. Check current feature enablement, region membership, participant consent, and any required room-admin/allowlist policy.
4. Re-check the target’s observed location and policy immediately before dispatch. A previously received locationEntered event is not sufficient for delayed or queued work.
5. Dispatch through its dedicated action and record honest outcomes. A send is not an acknowledgement; appearance changes require matching BC observation before they are reported as observed.
6. Cancel pending region-bound work on exit, disconnect, configuration change, or plug-in stop. Do not blindly retry ambiguous state changes.

The upstream ambient loop and chat-triggered behavior must both use this same gate. Filtering only initial events or only the scheduled loop would leave other action paths able to operate outside the region. Feature configuration should be room-scoped, validated, disabled by default, and include explicit participant eligibility/consent rules. No default policy should infer consent from appearance, chat content, or room presence.

Upstream source and update method

Source layout

After confirming redistribution/modification permission, keep upstream-origin files in a clearly marked, pinned subtree (for example src/features/abcl/upstream/) and keep Veratown code outside it:

• src/features/abcl/upstream/: only reviewed upstream behavior modules.
• src/features/abcl/adapter/: Veratown compatibility facade and protocol translations.
• src/features/abcl/actions/: dedicated journaled state-changing actions.
• src/features/abcl/: policy, configuration, plug-in lifecycle, and services.
• scripts/update-abdl-bot.ts: proposed dry-run-first import/update command.
• src/features/abcl/UPSTREAM.json: proposed source URL, exact commit SHA, import date, allowlisted source paths, and integration patch version.

Do not import upstream environment files, package manifests, lockfiles, runtime entry point, direct connector setup, deployment configuration, or bc-bot dependency. Keep the compatibility changes in a small, separately reviewable patch set or adapter layer; never silently edit an upstream snapshot. If the chosen upstream modules cannot be cleanly separated from connector/bootstrap code, stop and revise the source boundary rather than copying the whole bot.

Repeatable update workflow

The proposed updater accepts an explicit local checkout and commit. It never tracks a moving branch and never fetches or applies changes implicitly.

npm run update:abdl-bot -- --source /path/to/abdl-bot --commit <full-sha>
npm run update:abdl-bot -- --source /path/to/abdl-bot --commit <full-sha> --apply

The first invocation is read-only and reports the verified repository URL, commit, allowlisted file changes, and patch conflicts. The --apply invocation updates only the upstream-owned subtree and provenance manifest; it does not overwrite Veratown adapters, configuration, tests, or runtime wiring. The script must reject an unexpected repository, an unpinned/invalid commit, or changed paths outside the allowlist. It must not print secrets or use runtime BC/Mongo credentials.

Each update is then reviewed and validated as a normal code change:

1. Review the upstream commit range and the imported source diff; confirm licensing/permission still applies.
2. Review and reapply any small integration patch. Resolve conflicts manually; never treat a clean textual merge as behavioral compatibility.
3. Update compatibility mappings and tests for changed events, payloads, and action calls. Reject new upstream operations that have no approved typed Veratown implementation.
4. Run formatting, lint, type-check, tests, and build. Run focused protocol and feature tests, including exit/stop/reconnect cases.
5. Qualify against RUNTIME_TARGET=test, a dedicated BC account, and the test room. Review action journals and observed outcomes before production approval.
6. Update the manifest and feature guide, then commit the pinned update and adapter/test changes together. Keep the prior pin available for rollback.

The updater should be added only after the source boundary and license gate are settled. Until then, the same procedure can be performed manually with a reviewed patch; no automated copying should precede permission.

Testing and rollout

Required automated coverage

• Compatibility projection validation and unsupported/malformed payloads.
• Each mapped event and typed write intent through a fake Veratown adapter.
• Region match, region exit before dispatch, overlapping regions, stale observations, disconnect/reconnect, and disabled configuration.
• Consent and authorization rejection with no BC dispatch.
• Action journal outcomes for dispatched, observed, timed-out, and failed cases.
• Timer cancellation, event disposer cleanup, and plug-in stop/drain behavior.
• Upstream update dry run, allowlist rejection, pin verification, idempotence, and conflict reporting.

No unit test opens a BC or Mongo connection. Live qualification uses only dedicated test accounts and veratown_prototype_test.

Rollout gates

1. Confirm upstream licensing/permission and select the exact behavior scope.
2. Inventory call sites and approve the compatibility interface and safety policy before implementation.
3. Implement the feature disabled by default and qualify with test accounts.
4. Enable only in the test region for explicitly eligible participants.
5. Review logs, action journals, BC-observed outcomes, and stop behavior.

Rollback disables the feature and stops its plug-6. Obtain separate room/operator approval before any production activation. in before disconnecting BC. Do not roll back protocol or itemset assumptions without qualifying the resulting runtime against current stored configuration.

Risks and mitigations

Risk	Mitigation
bc-bot API behavior cannot be represented safely by the facade	Expose only required methods; adapt or exclude incompatible upstream behavior rather than emulating the full library
A delayed task acts after a participant leaves	Re-check observed region and consent immediately before dispatch; cancel queued work on exit
Upstream changes expand the required API surface	Pin revisions, import allowlisted files, report diffs, and require explicit adapter/test review
A write is dispatched but BC does not confirm it	Preserve dispatched_unconfirmed/timed_out_unobserved; reconcile before another state-changing attempt
Feature load affects the supervisor’s shared socket queue	Keep work bounded, rate-limited by the existing client, disabled by default, and test under the shared queue
Source license does not permit vendoring/adaptation	Do not import source; obtain written permission or implement independently
Ported behavior conflicts with participant boundaries	Require explicit consent/eligibility and deny by default; never infer consent from room state

Decisions required before implementation

• Confirm permission to copy, modify, and redistribute the upstream modules.
• Select the exact upstream behavior to integrate; do not assume all current bot behaviors are approved.
• Define the target room/region and participant opt-in/eligibility policy.
• Decide whether ABCL state is process-local or must survive restarts, then specify the validated storage contract and retention.
• Decide whether sharing the supervisor’s client/rate queue is acceptable for the initial rollout. A separate Veratown process can be considered later, but must still use the Veratown adapter and fixed runtime database mapping.

Acceptance criteria

• No bc-bot dependency, direct Socket.IO owner, or second connection is added to the Veratown process.
• The ABCL feature uses only statically composed Veratown ports and dedicated actions.
• Every side-effect path is region-, consent-, and permission-gated at dispatch.
• Observed BC state, not the compatibility facade’s request, determines completion of state-changing actions.
• The feature is disabled by default and can stop without affecting the other plug-ins or their lifecycle.
• Every adopted upstream revision is pinned, license-checked, diff-reviewed, tested, and recorded; updates never silently follow main.