Contributing to worldseq

Keep behavior in the module that owns it, use small typed functions, and validate changes through real public interfaces. These guidelines describe engineering practice; the implemented schemas, services and verifiers enforce runtime behavior.

Read the architecture before changing ownership or data flow. Follow the SDK and distribution guidance when changing public clients or packages. Use the documentation index to find the mechanism or operator contract involved.

Working checks

From the application directory, use bun run check:integration for formatting, linting, type checking, documentation, integration tests and the dashboard build. bun run test:integration runs just the selected tests. These cover public play, finalization, recovery, evaluation, verified imports and the dashboard, with focused accounting and isolation checks. Add regression or flow tests for consequential behavior; moving an unchanged helper does not need a new test.

bun run check retains the full automated suite, including the detailed mechanism cases and qualification checks. Run it before a release or when investigating changes beyond the routine flows. The integration suite is a quick development check, not a task certification campaign.

For dashboard changes, bun run dashboard:check runs formatting, linting, types, input and routing tests, and the production build. For the landing page and docs website, run bun run check, bun run verify:browser and bun run verify:docs from site/.

CI selects checks from changed files. Website-only changes run the website checks; dashboard changes also check the website’s shared components. Documentation changes check generated content and links as well as the website. Simulator, SDK, contract, packaging, tooling and unknown changes run integration checks and SDK validation. A manual CI run executes the full simulator suite, including real Docker integration. Playwright and other browser checks run locally only; GitHub CI does not install or launch browsers. Keep PostgreSQL available so persistence and import checks run. Use CI result as the required status check; it fails if selection or any selected job fails.

bun run docs:generate refreshes public company/task guides from the compiled public catalog. bun run docs:check verifies generation drift, MDX syntax and local links. Keep implementation checklists, experiment outputs and private preparation artifacts in ignored .runtime/ storage.

Release content and execution identities are distinct. Documentation and test-only changes affect release packages. Removing even unused execution inputs changes their identity. Preserve the old qualified artifacts and never relabel their certificates for a changed checkout.

Application boundaries

• worldseq is an independent Bun/Hono application. Keep routes, controllers, validators, episode services and PostgreSQL persistence separate. Keep the core independent of applications that consume it. HTTP/MCP adapters share the same canonical episode service; player access never implies control access.
• Maintain the public HTTP/MCP contracts and CLI in this package. Keep the standalone guides in docs/ and their website in site/.
• Keep replay-command schemas in a data-only module. Importing the episode service from persisted/evaluation schemas can create a runtime initialization cycle once the service imports finalization and those same persisted schemas.

Human interfaces and access

• Local human development connects through an HttpOnly browser session enabled by bun run dev; keep credential handling out of the UI. Automatic session issuance is explicitly opt-in, restricted to the loopback control listener and same-origin browser requests. Player listeners and isolated evaluation exports never accept this session. Diagnose rejected bearer credentials against the actual server’s launch configuration, not a token file left by another launch.
• Use the application’s Prettier, typed ESLint and readability rules. worldseq adds a 300-code-line file limit. Split by responsibility, not arbitrary line ranges. The dashboard uses shadcn source components and preserves a small UI surface. Use sidebar-07, square tabs, zero corner radius and self-hosted JetBrains Mono. Use shadcn’s standard neutral dark theme; limit sky blue (#87CEEB) to primary accents. Avoid decorative section rules; keep data-table boundaries useful and restrained.
• Build human flows from official shadcn blocks using the CLI. Show familiar business language, dollar amounts and named choices; keep engine IDs and optional tuning out of the main flow. Preserve unsaved plan state across navigation and test the actual browser submission at the typed engine boundary. Keep pure presentation tests in the dashboard TypeScript project.
• Give navigable entities and run sections their own URLs. Keep browse filters in the URL so Back/Forward restores context; don’t push an entry for each search keystroke. Verify direct reloads against the production server, not just Vite.
• Archived views reuse public projections under control authority; they must not re-enter expired player mutation authority. Public DTOs imported by the browser belong in types-only modules, without service/repository import graphs.
• Paginate shared history on the server using stable timestamp/identity cursors. Preserve PostgreSQL timestamp precision, bind cursors to filters, and test more than one page with tied timestamps and concurrent inserts. Infinite scrolling must cancel hidden reads, preserve position and stop automatic retries on failure.
• Test self-hosted fonts against the actual Content Security Policy. Disable Vite asset inlining when small font subsets would become blocked data URLs.
• Exercise new browser routes against the production server. Client-side routing and a Vite fixture can pass while the deployed SPA fallback rejects direct links.

Durable execution and monitoring

• Keep execution monitoring separate from score authority. Persist the full task inventory before workers start, derive activity from trusted runner heartbeats, and distinguish an open human session from a live worker. Stale activity must be visible; late heartbeats cannot reopen terminal monitoring records.
• Canonical JSONB persistence uses the driver’s json() parameter. Casting an already serialized JSON string can create a JSONB string instead of an object. Keep the object constraint and actual PostgreSQL restart/concurrency test.
• Parse persisted history per record. An unsupported old schema must remain visible without breaking current navigation or silently rewriting a sealed ledger. Mutations still require a fully compatible canonical record.
• Treat observability callbacks as untrusted consumers of detached projections. Mutation of a monitor frame must not alter simulator state, accepted commands or grading. Bound/coalesce telemetry work and distinguish missing pages from verified execution evidence.
• Keep lifecycle tests independent of optional live telemetry. Exercise monitoring in dedicated database tests with cleanup, so ordinary tests neither depend on dashboard availability nor leave test runs in a developer’s history.
• Finalization closes mutation authority in a separate committed write before expensive sealing or paired execution. Retain a recoverable claim and a stable journal-derived result key; artifact filenames must not affect grading identity.
• A reserved instance and an active player session have different clocks. Begin gameplay wall-time metering at durable session creation, preserve it on retries, and keep the one-use reservation intact while preparing runtime artifacts.

Business mechanics and accounting

• Scope randomness to stable world/semantic entity addresses, not process IDs, episode IDs, tool-call order or retry counts. Paired seed tests must use distinct run IDs; replaying one identical ID alone cannot detect this failure mode.
• For financial changes, reconcile cash, earned revenue, prepaid service, receivables and dated liabilities independently. Opening receipts cannot add episode cash; collecting a previously earned receivable cannot earn revenue a second time. Keep future repayment and severance obligations in terminal objective values.
• Before accepting participant numeric inputs, bound the complete downstream calculation. A finite forecast can overflow a squared loss; reject it at the schema boundary instead of accepting it and later declaring verifier failure.
• Apply reporting errors only to public observations. Preserve authoritative accounting, effective dates and explicit correction references; test that delayed corrections cannot overwrite a newer effective snapshot.
• Derive revenue baselines from actual eligibility and dependency rules. Conditional product adoption requires all paid ancestors; count shared prerequisites once. A sum of independent adoption rates can silently overstate a continuity target.
• Feasibility witnesses must fund ordinary maintenance as well as named interventions. Reserve existing commitments and arrange financing relative to the published cash floor and dated obligations. A witness omission does not prove task impossibility.
• Fix retention cohorts at a declared opening boundary. Separate new-customer growth, expansion and gross contraction, and independently reconstruct their numerator and denominator from paid contractual receipts.
• New lifecycle prerequisites can invalidate existing task horizons. Author scoring, capacity budgets and feasible plans together before enabling a prerequisite in ranked worlds. Keep controlled mechanism fixtures separate from playable tasks; their certificates establish only the exact registered predicates.
• Expose guaranteed commercial terms separately from uncertain response effects. Players need offered repayment, payroll and severance terms to make a fair plan; this does not require exposing future events or hidden customer behavior.
• Retain the public evidence needed across turns. An incremental page is not a complete memory: remember bounded unpaid invoices until a later payment or expiry, and preserve effective dates when retaining reports and corrections.
• Cash impossibility bounds may subtract only payments a successful trajectory cannot avoid. An outstanding liability is not automatically a cash payment; optional repayment must not turn a feasible world into a false impossibility proof.
• Check productive throughput after integer rounding, not only reserved hours and paid cost. A fractional daily allocation can consume a weekly budget while completing no work; a reference policy must either fund the smallest productive allocation or explicitly defer it.
• Treat readiness work as a business decision. Removing a compliance or onboarding gate can admit demand beyond service capacity; ordinary maintenance must not silently initiate growth unrelated to the task’s public objective.
• Give players enough dated evidence to reason about the scored quantity. Core usage alone cannot rank service exposure when paid add-on access also contributes to shortfall. Publish the component measures with existing observation delays, then reconcile them independently from primitive receipts.

Fairness, grading and validation

• Independent verification needs a different computation path. Reconstruct prices, payments and obligations from primitive receipts; comparing two summaries produced by one helper cannot establish that the helper is correct.
• Bind source contents, executable code, manifests and complete case schedules in evaluation registrations. Hashes of source IDs alone do not freeze evidence. Replay establishes trajectory consistency, not participant model identity.
• Public source packages and public test partitions are never confidential holdouts. Label authored response coefficients and unreviewed task admission explicitly; do not convert sourced descriptive profiles into executed mechanics.
• Keep evaluator-only scenario secrets out of public registrations and reports. Address draws cryptographically by cause and semantic entity; preserving a seed alone does not prevent agents from exploiting public schedules or reset tools.
• Constraint failure must rank below every eligible outcome, including negative cash. Keep raw business metrics separate from a declared ranking transform; assigning failure zero while ranking raw losses rewards early termination.
• Bind sensitivity labels to executable parameter changes and source contents. Reject unknown, unsupported or inapplicable settings. Keep unweighted sensitivity alternatives separate from statistical samples of real businesses.
• Freeze executable inputs while measuring or replaying a registered campaign. If inputs change, retain the old campaign as stale and register a new one; never refresh its hashes in place to manufacture current validation evidence.
• Final reporting must recheck the same registration it started with. If final verification or persistence fails, revoke any passing derived report before auxiliary cleanup; returning an error alone can leave a misleading artifact. Compare retained artifacts with hashes captured during verification; fresh checksums of current files alone can bless a replacement made afterward.
• Keep exact configuration identity, structural variety and demonstrated behavioral variety separate. Names, seeds and coefficient changes cannot establish a new strategy. Retain failed witnesses and test consequential interventions before counting a task as admitted; privileged feasibility witnesses are not agent baselines.
• Keep ordinary upkeep identical in mechanism comparisons. A better unrelated recovery action cannot validate billing-unit understanding; use independently graded forecasts when the intended difference is informational.
• Size confirmatory studies from explicit meaningful effects and the pilot’s noise, not a favorable observed pilot effect. Preserve scenario clusters and use valid paired binary outcomes for binary metrics. Fresh seeds do not make public worlds confidential holdouts.
• Bind offline branch identifiers and ordering to the frozen factual prefix and registered choices. Verify both branches even when the player omitted an answer; missing answers and invalid trajectories are different failures. Stream retained branches rather than holding every long seal in memory.
• A replayable private witness certifies existence for its exact registered instance. It must never become an action-sequence answer key for other players, or certify unseen generated instances by inheritance. Mandatory requirements belong in the public contract and shared verifier, not dashboard-only labels.
• Preserve proper diagnostic scores when adding pass/fail requirements. An identifiable conclusion, an acknowledged equivalence class and a probability forecast are different claims; do not invent a hidden confidence threshold.
• When a new evidence guarantee is mandatory, freeze that requirement in the registration. An optional result field alone cannot distinguish legacy evidence from a new result that omitted the required proof.
• A physical author witness and a player-information fairness review establish different properties. Bind both to the exact registered instance, and never issue a graded reset or transfer a certificate across execution identities.

Packaging and operational resources

• Container images can declare implicit writable volumes even when the runner provides no mounts. Inspect the pinned local image and reject declared volumes before starting an isolated participant.
• Test exported environments with the effective non-root user and dropped capabilities. Set executable modes while exporting scripts and copy every migration the runtime loads; a template-string test cannot establish startup.
• Check exported entrypoints independently of the source checkout and load their copied data. Checksums cannot detect omitted transitive dependencies. Surface retained trial exceptions when an orchestrator exits successfully without results.
• Retained trajectories can be much larger than metadata. Compress them, verify the compressed bytes before parsing, and bound both compressed and expanded sizes. Parallel workers return small summaries.
• Domain IDs and artifact paths have different contracts. Use deterministic safe artifact keys and retain original IDs in the manifest; do not weaken path validation to accommodate a generated directory name.
• Profile whole-episode hashing separately from small event hashing. Materializing a canonical JSON string can multiply memory for a long ledger. Chunked hashing must preserve the exact existing byte order, Unicode and optional-field semantics; differential tests against the original hash protect replay identity.
• Test optional ledger additions across a persisted-session transition, not only fully old and fully new seals. A historical prefix can omit a later report field; once its contract appears, later records must keep satisfying it. Registered campaigns still require one frozen execution throughout.
• Size macOS worker concurrency from representative long-run physical footprint and kernel memory pressure, not resident memory alone. Compression can make RSS appear small while the process retains several gigabytes of charged memory; more workers can increase swapping and reduce throughput.
• Test a standalone runtime as the input to its own exporter. Generated strict JSON lockfiles can differ from development lock syntax; re-export must preserve exact dependency integrity and the prepared execution identity.
• Long private preparation campaigns require a process-held OS lock, not an empty lockfile or timeout-based ownership guess. Keep its inode stable across retries. Recover completion from the independent certificate and retained journal; preserve truncated attempts. When executable repairs require new certification, explicitly revise the entire unissued seed plan while keeping every private realization and retiring the old issuance authority; never redraw failed cases.