Imported from FuzzySlipper/asha-engine (AGENTS.md). Install upstream with npx skills add FuzzySlipper/asha-engine. Copyright stays with the author.

AGENTS.md (Autogenerated)

WARNING: This file is autogenerated. The project-local fragment agents-project.md is the source of truth. Shared/global agent policy lives in Den guidance documents, not in this file.

Generation sources:

• Den guidance: get_agent_guidance(project_id="asha")
• local: agents-project.md

Den Guidance Bootstrap

• Project ID: asha
• Resolve live guidance with the Den MCP get_agent_guidance tool or den guidance before substantial work.
• Treat the resolved Den guidance packet and its referenced Den documents as the source of truth.
• If Den is unreachable, stop and tell the user which Den tool or command failed and what you were about to do. Do not reconstruct Den state from local files.
• Use the project-local notes below only as bootstrap context for connecting to Den and working in this repository.

ASHA Engine Local Bootstrap

Live project guidance lives in Den. Use project ID asha for Den tasks, messages, documents, librarian queries, and guidance lookups.

When creating or updating Den tasks for this repository, tag them with asha-engine plus any lane/system tags.

Source-of-truth posture

This local file is bootstrap context for agents entering the repository. It is not the current planning queue.

• Den owns current task state, implementation queues, durable planning docs, review packets, and known limitations.
• Repo docs describe architecture and committed implementation surfaces.
• The code/tests are the implementation truth when they conflict with old planning prose.
• Resolve live Den guidance with get_agent_guidance(project_id="asha") before substantial work.
• The old prototype phase list is historical only; do not infer active work from it.

Architecture Soul

Rust owns authority. TypeScript owns expression and projection. Generated contracts define the border.

• Rust is authoritative: canonical state, validation, event application, deterministic services, replay, serialization, heavy simulation, and render projection generation.
• TypeScript proposes commands via constrained policy/catalog packages, displays projected state via shell/render/UI, and provides devtools/operator readouts.
• TypeScript never mutates authoritative state. Rust validates all commands.
• Every crate/package is an agent assignment cell with machine-checkable dependency rules.
• Protocols are generated from Rust; hand-editing generated files is forbidden.

See docs/design.md, docs/agent-code-atlas.md when present, and README.md for current repo orientation.

Repository Structure

/asha-engine          # repo name in design, maps to /home/dev/asha-engine
  /governance           # lane docs, ADRs, reviewer prompts, ownership config
  /harness              # CI, lints, depgraph checkers, goldens, fixtures, smoke/perf output
  /engine-rs            # Rust cargo workspace
    /crates
      /foundation       # core IDs, math, time, errors, collections, coordinates, assets
      /state            # core-state, core-entity, core-scene, core-catalog, core-voxel, commands/events/snapshots
      /protocol         # protocol schemas + protocol-codegen
      /sim              # sim-kernel, validator, applier, replay, runner
      /services         # rng, spatial, collision, physics, pathfinding, serialization, volume, mesh, policy-view
      /rules            # lifecycle, process, scheduler, relationship, state-machine, voxel-edit, project-bundle migration lanes
      /render           # render-bridge, render-debug
      /bridge           # runtime-bridge-api manifest; native-bridge napi addon is built explicitly
      /wasm             # wasm-api replay/golden surface
      /tools            # replay, diagnostics, protocol dump, state inspector, fixture maker, asset import
  /ts                   # pnpm workspace
    /packages
      /contracts        # generated TypeScript from Rust protocol crates
      /script-sdk       # policy authoring SDK
      /script-host      # policy execution sandbox
      /policy-*         # constrained policies
      /catalog-*        # typed catalog definitions/examples
      /runtime-bridge   # transport-neutral runtime facade + render-diff decode
      /native-bridge    # loader for compiled napi-rs runtime addon
      /wasm-replay-bridge # WASM replay/golden bridge for tests/devtools
      /renderer-three   # Three.js projection from render diffs
      /editor-tools     # pure editor state, previews, command builders
      /ui-dom           # panels, inspectors, command palette
      /devtools         # diagnostics/readout panels
      /smoke            # launchable/smoke/perf harnesses
      /app              # composition and wiring
      /electron-main    # thin host wrapper
  /docs

Local Commands

# Full gate
./harness/ci/check-all.sh

# Focused gates
./harness/ci/check-rust.sh      # cargo fmt --check, cargo check, cargo clippy --workspace -- -D warnings, cargo test
./harness/ci/check-ts.sh
./harness/ci/check-depgraph.sh
./harness/ci/check-contracts.sh
./harness/ci/check-replays.sh
./harness/ci/check-render-goldens.sh
./harness/ci/check-bridge.sh
./harness/ci/check-vocabulary.sh # ECRP term-gravity gate: bans *Component/*Archetype type names; gates legacy World* naming behind harness/vocab/legacy-term-allowlist.txt

# Rust lane quick checks when a full Rust gate is too broad
(cd engine-rs && cargo clippy --workspace -- -D warnings)
(cd engine-rs && cargo clippy -p <crate-name> --all-targets -- -D warnings)

# Launchable voxel smoke / shell / perf
cd ts
pnpm --filter @asha/smoke dev:asha-smoke
pnpm --filter @asha/app dev:asha-shell
ASHA_PERF_HOST=<stable-host-label> pnpm --filter @asha/smoke dev:asha-perf

See docs/launchable-voxel.md and docs/perf-baseline.md for command details, output paths, and known limitations.

Current consumer-facing RuntimeSession/ECRP docs include:

• docs/runtime-session-facade.md — current RuntimeSessionFacade API and non-claims.
• docs/ecrp-runtime-session-readout.md — ProjectBundle-shaped ECRP load/readout behavior.
• docs/ecrp-fps-object-model.md — FPS object-model capability map for the generated-tunnel loop.
• docs/ecrp-capability-rule-ownership.md — rule-owner matrix and current FPS RuntimeSession authority slice.
• Den guidance asha/ecrp-vocabulary-taxonomy — accepted ECRP naming and stored/runtime/projection taxonomy.

Agent Lane Quick Reference

Design Principles

• Boring architecture: Libraries you call > frameworks that call you.
• Infrastructure first: Enable expressive gameplay through stable public machinery, then validate it through real behavior.
• Replay is operational memory: Every state change must be replayable or intentionally documented as outside replay scope.
• Desired failure mode: The agent cannot compile the wrong thing.

Test and Acceptance Posture

• A local guardrail prevents an invalid dependency, authority leak, generated-border drift, unsafe wire shape, or data-loss path.
• A provider regression executes an engine-owned public/generated seam and asserts accepted/rejected behavior, readback, call count, or deterministic replay.
• A synthetic conformance check exercises the engine as an external consumer and belongs in asha-testing when it has a distinct public contract.
• Consumer acceptance observes usable Demo gameplay or Studio authoring and belongs in the owning downstream repository.

Engine CI may block on the first two. It must not infer downstream delivery from source tokens, manifests, evidence catalogs, or an engine-only report. Computed run results belong in ignored CI/task artifacts unless they are intentional protocol, replay, render, or serialization goldens reviewed as product inputs.

Use ./harness/ci/check-fast.sh for ordinary affected-surface iteration. Reserve the full inventory for scheduled/campaign closure, explicit native verification, or the selector's fail-safe expansion; reviewers should not demand it for an unrelated narrow change. Source-shape, vocabulary, and generated navigation warnings are review signals, not architecture law. Discuss their concrete impact and named next action proportionately.

A user-facing task cannot close from structural evidence alone. New blocking gates require a consequential failure class, owner, bounded trigger and fallback, representative regression, rough cost, and narrowing/removal condition. See harness/ci/guardrail-policy.json and docs/guardrail-policy.md.

TypeScript House Style

TypeScript in this repo is written for agent governance, not clever human terseness.

Prefer longer, clearer code over compact clever code. Use named intermediate values for meaningful decisions. Split work into small functions with explicit verbs. Avoid generic abstractions until duplication has stabilized. Keep mutation local and visible. Do not create ambient state, manager classes, global registries, or hidden runtime coupling.

A good TypeScript diff should be easy for a reviewer agent to inspect mechanically: imports reveal lane boundaries, functions reveal intent, tests reveal behavior, and public API changes are explicit.

When in doubt, write the boring version.

Rust House Style

Rust in this repo should be boring authority code. Prefer explicit state, explicit errors, explicit events, and narrow crate APIs. Do not introduce clever abstractions, runtime escape hatches, or framework-shaped machinery unless a lane owner explicitly approves them.