Asupersync Mega Skill

Asupersync is a spec-first runtime for structured concurrency, cancel-correct effects, obligations, deterministic testing, and capability security—not a Tokio wrapper. Verify against live evidence.

For release, live-support, or open-boundary questions, start with the current-status card in [SOURCE-MAP.md](references/SOURCE-MAP.md#release-and-live-head-status). Otherwise load the single task lane below first. Live source, tags, registry state, and terminal proof receipts outrank examples or stale tracker labels.

Table of Contents

• [Bootstrap](#bootstrap)
• [Choose One Lane](#choose-one-lane)
• [Non-Negotiables](#non-negotiables)
• [Migration Workflow](#migration-workflow)
• [Proof and Repository Rules](#proof-and-repository-rules)
• [Skill Validation](#skill-validation)

Bootstrap

Use #[asupersync::main] when the application does not need to own the runtime:

#[asupersync::main]
async fn main() {
    println!("hello from asupersync");
}

Use RuntimeBuilder when it does. Runtime-spawned tasks receive a runtime-owned Cx; pass &Cx into application code. Use production request-context APIs, explicit spawn admission, and checked joins rather than test constructors or implicit authority. For handle-only request contexts and caller-owned blocking pools, read [RUNTIME-CONTROLS](references/RUNTIME-CONTROLS.md); attaching a pool does not install a scheduler or a worker-local lane.

Choose One Lane

Load one primary reference first. Follow its links only when the task reaches that boundary; do not preload whole clusters.

Use browser/Wasm, QUIC/H3, messaging, distributed, or RaptorQ lanes only when requirements call for them.

Non-Negotiables

• Do not treat Asupersync as an executor swap.
• Put &Cx first in async APIs you control.
• Use Scope and child regions for owned work. Avoid detached background tasks.
• Use Cx::spawn / Cx::spawn_in for ordinary region-owned task creation.

Scope::spawn_registered is a lower-level boot/test path for callers already holding &mut RuntimeState.

• Add cx.checkpoint() in loops, retry bodies, long handlers, and shutdown-sensitive code.
• Prefer cancel-aware primitives and two-phase effects.
• State the layered v0.4.4-v0.4.9 cancellation contract precisely: ordinary Cx::spawn*

preserves a typed result returned after cancellation acknowledgement (a concurrent abort no longer erases it), but pre-first-poll cancellation and cancellation-blind late values keep v0.4.3 task-level cancellation, and JoinSet, cancellation-dominant combinators, blocking wrappers, and low-level state tasks retain their separately tested policies. Neither "abort always wins" nor "the value always survives" is correct. Explicit cancellation wakes timer-parked native tasks; Sleep retires its registration and completes with () while timeout/deadline combinators retain outcome classification. Native worker tests, not Lab-only models, prove this boundary.

• Cx::spawn_local requires a worker-local lane owned by the same runtime. A

direct Runtime::blockon, entry-macro body, runtest, or runtestwithcx does not by itself install that lane and may return LocalSchedulerUnavailable (ASUP-E004). Enter a real worker with runtime.blockon(runtime.handle().spawn(async { ... })), obtain Cx::current() there, then spawn the !Send future and prove it reached the parked state before aborting it.

• Use deterministic tests as part of normal development, not as optional polish.
• Treat Cx::fortesting() and Cx::forrequest() as test/internal harness

paths, not production architecture.

• Keep Tokio and Tokio-only crates behind explicit adapter modules if you must keep them at all.
• asupersync-tokio-compat adapts selected traits and context; it does not install a Tokio runtime

or prove Handle::current()-dependent frameworks. Require downstream compile and runtime evidence for every bridge.

Migration Workflow

1. Inventory direct and transitive Tokio-ecosystem dependencies.
2. Classify each as native replacement, explicit compat holdout, or deliberate

workaround.

1. Use the repository's migration readiness planner when available; do not

confuse a cargo tree grep with a plan.

1. Replace bootstrap, thread &Cx through owned APIs, then replace detached

spawning with region-owned work.

1. Migrate time, sync, I/O, channel, web, database, and protocol slices one at

a time.

1. Add deterministic and native cancellation tests during the migration.
2. Compile actual external-consumer feature profiles; cfg(test) access and

repo-internal tests are not downstream API evidence.

1. Remove each compat boundary when its last justified dependency is gone.

The planner's summary.finalverdict, proofpack.proofcommands, semanticmap.recommendations, and operatorreport.phaseplan are inputs to the decision. scripts/audit-target.sh is only bounded inventory; its optional Cargo graph probe is explicit and can touch Cargo state.

For more-than-parity design: [LEVERAGE-PLAYBOOK](references/LEVERAGE-PLAYBOOK.md), [BUDGET-OUTCOME-CAPABILITIES](references/BUDGET-OUTCOME-CAPABILITIES.md), [SUPERVISION-OTP](references/SUPERVISION-OTP.md), and [ADVANCED-FEATURES](references/ADVANCED-FEATURES.md).

Other routers: [adoption](references/ADOPTION-LANES.md), [anti-patterns](references/ANTI-PATTERNS.md), [compat bridge](references/COMPAT-BRIDGE.md), [replacement matrix](references/TOKIO-REPLACEMENT-MATRIX.md), [performance](references/PERFORMANCE-AND-SCHEDULING.md), [browser frameworks](references/BROWSER-FRAMEWORKS.md), and [mathematics](references/MATHEMATICAL-FOUNDATIONS.md).

Secondary deep dives, only when a primary card routes there (except the two direct routes named above): [greenfield patterns](references/GREENFIELD-PATTERNS.md), [Tokio mappings](references/TOKIO-MAPPING.md), [compat limits](references/COMPAT-BOUNDARY.md), [scheduler internals](references/SCHEDULER-INTERNALS.md), [channel/sync internals](references/CHANNELS-SYNC-INTERNALS.md), [lock ordering](references/LOCK-ORDERING.md), [support classes](references/STACK-SURFACES.md), [Lab/DPOR](references/LAB-TRACE-DPOR.md), and [error taxonomy](references/ERROR-TAXONOMY.md).

Proof and Repository Rules

• Run the host formatter, compiler, linter, and tests; verify cancellation,

shutdown, and resource release, not compilation alone.

• For an escaped concurrency defect, reproduce the same public API sequence on

the native runtime, prove the formerly failing parked/owned state, assert the exact nested result and cleanup, and retain old-red/new-green evidence. A Lab-only or compile-only test is not a substitute.

• RCH pre-admission refusal, exit 103, worker assignment, a job id, a PID, or

local fallback means zero admissible executed tests. Green proof requires terminal output naming the target and nonzero pass counts from the required environment.

• Do not key source or evidence authority to /dp, /data/projects, or an RCH

checkout prefix. Identify the repository by content and declared root.

• Never invoke a waker, user callback, observer, or extension hook while a

runtime-state lock is held. Treat unresolved tracker rows as unshipped boundaries, not capability claims; refresh them from the status card and live tracker before reporting current state.

• Exact ForcedSchedule files are bounded Lab replay evidence, not production

scheduler control, authenticity proof, or automatic minimization.

• Support classes come from live implementation and proof: default production,

optional production, experimental/guarded, compat-only, test/fuzz-only, or planned. Do not promote a class from prose alone.

Inside Asupersync, follow live AGENTS.md and TESTINGFORAGENTS.md; work on main, do not delete files without permission, and preserve the v0.4.3 public API and documented behavior throughout 0.4.x. Classify proof through artifacts/prooflanemanifestv1.json and artifacts/proofstatussnapshotv1.json: manifest = command/claim/envelope; snapshot = freshness/blockers; only a terminal receipt proves execution. Preserve build id, target/artifact roots, and dirty-tree state. Use Beads and CASS for rationale, corroborated by tagged source and focused evidence.

ATP performance claims require live ledger/matrix artifacts, tuned rsync, release atp, symmetric crypto, caps, and SHA/tamper checks. A cell proves only its scope; compilation or sha_ok is not a benchmark win.

Skill Validation

After editing this package run:

./scripts/validate.sh
ASUPERSYNC_SOURCE_ROOT=/path/to/asupersync ./scripts/validate.sh

The second form also validates referenced repository paths and release-sensitive source anchors. It does not compile Asupersync or replace RCH proof.