Asupersync Mega Skill

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. 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
• Choose One Lane
• Non-Negotiables
• Migration Workflow
• Proof and Repository Rules
• 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; 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 current-thread runtime installs that lane on the caller during block_on, so its root Cx accepts !Send local tasks. A context from another runtime or a harness without a local lane still returns LocalSchedulerUnavailable (ASUP-E004). For other runtime flavors, enter an owner worker with runtime.block_on(runtime.handle().spawn(async { ... })) and obtain Cx::current() there. Cancellation evidence must prove the local task reached the parked state before aborting it.
• Use deterministic tests as part of normal development, not as optional polish.
• Treat Cx::for_testing() and Cx::for_request() 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.
3. Use the repository's migration readiness planner when available; do not confuse a cargo tree grep with a plan.
4. Replace bootstrap, thread &Cx through owned APIs, then replace detached spawning with region-owned work.
5. Migrate time, sync, I/O, channel, web, database, and protocol slices one at a time.
6. Add deterministic and native cancellation tests during the migration.
7. Compile actual external-consumer feature profiles; cfg(test) access and repo-internal tests are not downstream API evidence.
8. Remove each compat boundary when its last justified dependency is gone.

The planner's summary.final_verdict, proof_pack.proof_commands, semantic_map.recommendations, and operator_report.phase_plan 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.

From the repository root, use scripts/migration_readiness_planner.py:

python3 scripts/migration_readiness_planner.py --dry-run --scenario tokio-http-service
python3 scripts/migration_readiness_planner.py --project-root /path/to/rust/project --output-root target/migration-readiness
python3 scripts/migration_readiness_planner.py --execute --output-root target/migration-planner-fixtures

--execute runs the planner's fixture scenarios; it does not execute the generated proof commands or establish downstream runtime correctness.

For more-than-parity design: LEVERAGE-PLAYBOOK, BUDGET-OUTCOME-CAPABILITIES, SUPERVISION-OTP, and ADVANCED-FEATURES.

Other routers: adoption, anti-patterns, compat bridge, replacement matrix, performance, browser frameworks, and mathematics.

Secondary deep dives, only when a primary card routes there (except the two direct routes named above): greenfield patterns, Tokio mappings, compat limits, scheduler internals, channel/sync internals, lock ordering, support classes, Lab/DPOR, and error taxonomy.

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 TESTING_FOR_AGENTS.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/proof_lane_manifest_v1.json and artifacts/proof_status_snapshot_v1.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. If the sw skill is installed elsewhere, set ASUPERSYNC_SKILL_VALIDATOR to its sw/scripts/validate-skill.py path for either command.