DEV Community: loach

PC Engine CD BIOS Progress: 8 DEV Entries, 0 Verified Compatible APIs

loach — Thu, 22 Oct 2026 03:26:53 +0000

I'm working on oss-pce-cd-bios, an effort to build an open-source replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

My previous update focused on original HuC6280 routines and a synthetic CD-to-ADPCM DMA diagnostic. This update has a more visible milestone:

The development ROM now has eight implemented entry points out of 81 candidates, up from just one in the previous post.

That's genuine implementation progress. But it is not the same as eight compatible System Card services, and it doesn't mean any commercial CD game boots.

From standalone routines to actual DEV ROM entries

The current 256 KiB development-only image has project-owned implementations installed at these candidate jump-table slots:

Slot	Routine	Purpose
`$1E`	`EX_GETVER`	Development version response
`$3C`	`EX_BINBCD`	Numeric conversion
`$3D`	`EX_BCDBIN`	Numeric conversion
`$3F`	`MA_MUL8U`	Unsigned 8-bit multiplication
`$40`	`MA_MUL8S`	Signed 8-bit multiplication
`$41`	`MA_MUL16U`	Unsigned 16-bit multiplication
`$42`	`MA_DIV16S`	Signed 16-bit division
`$43`	`MA_DIV16U`	Unsigned 16-bit division

The remaining 73 slots are nonreturning stubs, not functional API implementations.

Previously, several math and conversion routines were tested only as independent components. They have now been wired into the development ROM's actual entry points and exercised under a project-defined calling convention with a pinned Geargrafx core.

The newest addition, MA_DIV16U in PR #480, checks quotient/remainder behavior, divide-by-zero handling, stack boundaries, caller interrupt/decimal flag combinations, and changes across the 8 KiB working RAM. Deliberately modified variants must be rejected for the expected reason rather than merely producing any failure.

The signed/unsigned arithmetic routines are original implementations, and their DEV-side contracts are being tested. They are not claims of compatibility with the proprietary reference System Card ABI.

Why 8/81 isn't a compatibility percentage

The project now tracks separate measurements instead of merging different kinds of evidence into one progress bar:

Measurement	Current main
Project-defined DEV ROM entries implemented	8/81
Remaining nonreturning stubs	73/81
Reference BIOS ABIs independently VERIFIED	0/81
Owner-approved DEV_CALLABLE entries	0
Reference BIOS JSR executions permitted by the current gate	0/81
Verified BIOS-mediated CD program boots	0

This distinction is important. An entry can execute and return according to our development contract without proving that a game can call it using the original System Card's parameters, registers, flags, memory layout, or error behavior.

In other words, the source code has advanced much faster than compatibility certification. The latter remains intentionally conservative.

The current status ledger documents these independent axes.

Learning about the reference BIOS without executing it

The static ABI investigation in PR #472 added a local-only auditor and evidence ledger for seven reference BIOS entry points.

Instead of jumping directly into proprietary firmware code, the audit records narrowly scoped static properties: control-flow shape, memory writes, bank-register operations, and hazards that would make an execution experiment unsafe.

One important observation is that some reference math entry points are dispatchers that change memory page registers. An apparently simple multiplication API can therefore carry hardware-visible side effects that an independent arithmetic routine does not reproduce.

A static safety classification is not permission to run the reference code. The project still blocks all 81 reference JSR entry points. No proprietary BIOS bytes, extracted code, or commercial game content were published with this work.

A guard can detect trouble too late

Another revealing experiment is PR #481, which tested a synthetic HuC6280 caller/stack contract on a pinned, unmodified Geargrafx core.

With the expected WRAM stack mapping, the test caller returned and its measured CPU state was preserved. With the stack mapped to I/O instead, the CPU's JSR and subsequent stack pushes changed VDC state before the guard detected the invalid mapping.

This demonstrates a subtle failure of the “check, then refuse” approach: checking after a side-effecting instruction cannot undo the side effect that already happened.

The result doesn't prove a production-safe guard exists. Nor is the experiment a complete I/O bus trace or a real-hardware result. It provides a reproducible counterexample that the eventual safety design must address.

What's next?

As of October 22, 2026, the goal is still a genuinely compatible and redistributable System Card implementation—not merely a development ROM with increasingly many working routines.

The immediate work is to verify caller-visible ABI contracts safely, establish testable CD services such as CD_RESET and CD_READ, and eventually boot a self-authored disc through actual BIOS services. Comparison against a second emulator and physical hardware will be needed before broader compatibility claims.

No retail game boot has been demonstrated. The reference ABI has zero VERIFIED entries. The release gate remains blocked (release_eligible: false).

Going from one to eight implemented DEV entries is meaningful progress. Keeping that separate from “eight compatible BIOS APIs” is just as important.

Repository: https://github.com/mao2009/oss-pce-cd-bios

This is an independent project, unaffiliated with NEC, Hudson Soft, Konami, or other rights holders. It does not distribute proprietary BIOS images, commercial game images, or game-derived content.

PC Engine CD BIOS Progress: Tested HuC6280 Routines and ADPCM DMA

loach — Wed, 21 Oct 2026 03:48:30 +0000

I'm building oss-pce-cd-bios, an open-source project aiming for a redistributable replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

In the previous update, I described reading sectors from a self-authored CD image and executing a small synthetic HuC6280 payload from RAM. Those were isolated diagnostic experiments—not CD game boot.

Since then, the focus has moved toward implementing original low-level routines and testing their actual effects in a pinned emulator core. The results are useful, but it's important to keep the boundary between a tested routine and a compatible BIOS service explicit.

Seven original routines exercised in the actual CPU core

One tangible change is a set of independent HuC6280 assembly routines. The current opt-in real-core test target covers seven:

EX_BINBCD and EX_BCDBIN (numeric conversions)
MA_MUL8S and MA_MUL8U (8-bit multiplication)
MA_MUL16U (16-by-16-bit unsigned multiplication)
MA_DIV16U and MA_DIV16S (16-bit division)

These aren't just Python models: the test harnesses execute original guest instructions with a pinned Geargrafx core and check outcomes and relevant CPU state. For example, the unsigned 16-bit division work exercises edge cases and 65,536 generated operand pairs while checking quotient/remainder invariants, register/stack behavior, and deliberately broken variants.

An additional EX_RND implementation provides an original 16-bit LFSR-based random-number routine with its own tests.

None of these standalone routines has been promoted to a caller-compatible System Card API. Their local contracts are not automatically the reference BIOS calling conventions. In particular, they are not connected to the development ROM's API jump table.

The real-core integration change records the seven-routine target; the division implementation is a concrete example.

Moving a synthetic CD sector through ADPCM DMA

The earlier CD read experiment transferred sector data into ordinary guest RAM. A newer experiment exercises a different hardware path.

A self-authored HuC6280 guest issues SCSI READ(6) through the emulated CD interface and arms ADPCM DMA via register $180B, moving data into ADPCM RAM starting at $0100. The host probe observes the resulting device state and memory; it does not perform the transfer by directly calling a host-side ADPCM write method.

The test includes both a successful transfer and a negative case where DMA is not armed. It also stores the raw observations, rechecks them against the source/build hashes and known toolchain/core versions, and verifies that twelve selected manipulations of the evidence are rejected.

That extra evidence work matters: if a result can't be reproduced or its recorded inputs can't be bound to what actually ran, a green status is much less informative.

The ADPCM DMA experiment was merged on October 21.

But the boundary remains clear: this is a device-layer transfer diagnostic. It does not implement the System Card AD_TRANS service, establish its ABI, or make the BIOS bootable.

Observing CD status and subcode-Q without claiming BIOS compatibility

Two more lines of investigation now have real-core observations.

For the CD status work, a test distinguishes a synthetic disc from no media and checks how cases such as an unrecognised disc and selection timeout are classified. For subcode-Q, the project decodes an observed $DD response and checks track/time/status information at a particular synthetic-disc location.

The real-core subcode-Q result is deliberately narrow: track 2 at LBA 66, with playing, paused, and stopped states. Other track boundaries have host-side synthetic tests, but those cases have not all been measured in the actual emulator core.

These investigations provide building blocks for future CD_STAT and CD_SUBQ work. They do not mean their reference System Card entry points have been executed or reproduced.

See the CD status diagnostic and subcode-Q diagnostic.

Making the test boundary harder to misunderstand

The default test workflow has also been clarified:

make test            # build and host-side checks
make test-real-core  # required Geargrafx integration checks
make routine-real-core  # opt-in standalone routine checks

The required CI path still runs the real-core checks; they weren't removed to make the host suite greener. The separate standalone-routine target remains opt-in rather than a required CI gate. Missing prerequisites and tests that haven't run must not be reported as passing observations.

Another diagnostic now checks all 8 KiB of working RAM around a synthetic ROM-to-RAM handoff, rejecting unexpected modifications. It does not read code from a CD or demonstrate the actual CD_EXEC API.

So how many BIOS APIs actually work?

The honest answer is still small.

The development ROM has 81 candidate API slots, and exactly one is callable as a development-only service: EX_GETVER. The other 80 slots remain nonreturning stubs. Adding independently tested arithmetic routines does not change that number.

The reference System Card ABI remains unverified. Callable CD_RESET, CD_READ, and CD_EXEC services, BIOS-mediated homebrew CD boot, commercial-game compatibility, and a releasable firmware image are still missing. The release gate remains blocked.

The distinction is the central point of this update:

A tested HuC6280 routine isn't necessarily a compatible BIOS API. A demonstrated DMA path isn't AD_TRANS. An observed CD status response isn't a finished CD_STAT service.

Still, these experiments move the project from preparing diagnostic scaffolding toward original, measured building blocks. That's the progress I want to report—without claiming a usable replacement BIOS before the evidence supports one.

If you're interested in HuC6280 assembly, firmware replacement, CD-ROM² devices, or emulator-driven verification, technical feedback is welcome.

Repository: https://github.com/mao2009/oss-pce-cd-bios

This is an independent project, unaffiliated with NEC, Hudson Soft, Konami, or other rights holders. It does not distribute proprietary BIOS images, commercial game images, or game-derived data.

Building an Open-Source PC Engine CD BIOS: From Reading Sectors to Running Code from RAM

loach — Fri, 16 Oct 2026 04:21:00 +0000

I'm working on oss-pce-cd-bios, an open-source effort to create a redistributable replacement for the PC Engine / TurboGrafx-CD System Card BIOS.

The initial long-term target is behavior compatible with Super System Card 3.0, using original code and third-party OSS only where its licensing and suitability have been reviewed.

The project does not have a usable replacement BIOS yet. No commercial CD title has been shown booting with it. But the development experiments have progressed from building diagnostic ROMs to reading a synthetic CD sector and executing code loaded from it.

Here's what has been established so far—and what hasn't.

Getting useful evidence from the real emulator core

The PC Engine uses a HuC6280 CPU, bank-switched memory, and a separate CD-ROM interface. A replacement System Card needs more than a ROM file with the expected size: it needs correct startup behavior, bank mapping, calling conventions, and device interactions.

I'm using a pinned build of Geargrafx as the first instrumented execution environment.

The repository now builds original diagnostic ROMs and checks actual CPU execution, including program-counter transitions, MPR (memory page register) state, stack behavior, and working RAM. There are also deliberately broken ROM variants that must fail the same checks.

The 256 KiB development image includes a scaffold for 81 candidate System Card API slots. Those entries are placeholders that stop rather than return success. None of those 81 services is implemented as a compatible BIOS API yet.

Diagnostic API scaffold and its limits

Reading 2,048 bytes from a synthetic CD

The next step was an independent, development-only HuC6280 program that drives the emulated CD-ROM² controller.

It sends a SCSI READ(6) command through the CD interface registers and transfers a MODE1 data sector to guest RAM. The verifier checks all 2,048 user-data bytes against a separately generated reference. A three-sector, 6,144-byte case is covered too.

This runs through guest HuC6280 instructions in the actual Geargrafx core, rather than copying the expected data into RAM from the host side. Cold- and warm-reset cases are checked, along with negative scenarios such as invalid addresses, damaged disc data, and interrupted transfers.

This is an important low-level milestone, but it is not the System Card CD_READ API. Its calling convention, return behavior, interrupts, retries, and compatibility with real hardware remain separate work.

CD sector-read diagnostic

A new milestone: load code from CD and execute it in RAM

The most recent experiment connects a few of these pieces into one traceable sequence.

A small, independently assembled 28-byte HuC6280 program is embedded in sector 5 of an entirely synthetic CUE/BIN image. The development ROM then:

Synthetic CD sector (LBA 5)
             |
       SCSI READ(6)
             |
   2,048 bytes into RAM
             |
   Validate payload header
             |
     Copy code to $3000
             |
      Jump to RAM code
             |
   Write observable markers
             |
 Return to diagnostic ROM
             |
       Confirm halt

The test checks the order of the actual execution checkpoints, the bytes copied into RAM, and the marker values written by the downloaded code. It also confirms the return to the diagnostic ROM and the final halt over 64 instructions.

Corrupting the payload checksum, header, or entry offset must prevent execution. Other negative tests ensure that simply reaching an expected-looking result cannot substitute for the correct execution path.

This is a custom load-and-execute experiment, not CD game boot. It does not implement the System Card boot process or prove that any existing game can run.

Load-and-execute implementation and evidence

The less visible work matters too

A few supporting pieces have landed alongside the ROM experiments:

Disc inspection: CUE/BIN and TOC diagnostic tools check track boundaries, INDEX 00/01, pregaps, LBA/MSF calculations, and malformed inputs using synthetic fixtures.
Bus-reset observation: a separate Geargrafx experiment measures two reset pulses through $1804 and verifies the bus is free afterward. This is not proof of the System Card CD_RESET service.
Evidence and isolation: an isolated trace harness distinguishes PASS, FAIL, BLOCKED, and SKIP instead of treating missing prerequisites as success.
Source provenance: an automated guard checks for suspicious binary or proprietary material in changes. It reduces risk but is not a legal guarantee; adopting third-party code still requires human review.

The current main-branch diagnostic CI has passed for the latest load-and-execute work. Reproducing and checking the scope of those results is part of the project, not an afterthought.

Where this goes next

A useful homebrew-CD boot path is still ahead, followed by validated System Card entry points, error handling, interrupts, and comparison against an independent emulator and eventually real hardware.

I want to keep the evidence labels precise:

A ROM that loads is not a BIOS that boots. A sector that reads is not an implemented CD_READ service. A 28-byte test program running from RAM is not commercial game compatibility.

Still, being able to follow bytes from a self-authored disc, through the guest CD interface, into RAM, and then watch the guest CPU execute those bytes is genuine progress.

If you work on HuC6280 assembly, CD-ROM² emulation, firmware replacement, or reproducible compatibility tests, I'd welcome technical feedback.

GitHub: https://github.com/mao2009/oss-pce-cd-bios

This project is independent of NEC, Hudson Soft, Konami, and other rights holders. It does not distribute proprietary BIOS images, commercial games, or game-derived disc data.

PSXRecompStudio Progress: Persona's Opening, a Recompiler Demo, and a Runtime Mystery

loach — Fri, 16 Oct 2026 04:01:23 +0000

I'm building PSXRecompStudio, an open-source research project exploring static recompilation of PlayStation 1 software.

The long-term goal is to help authorized rights holders turn existing PS1 games into maintainable, rebuildable ports, even when their original source code and build tools are no longer available.

This is still research-stage work, not a way to recompile and play a complete commercial game today. But over the past few weeks, several parts of the project have become much easier to demonstrate and measure.

Seeing Persona's opening for the first time

One of the most encouraging milestones was getting visible opening imagery from Megami Ibunroku Persona (Revelations: Persona) through the OpenBIOS interpreter execution path.

I added screenshots captured at specific VBlank intervals rather than trying to reconstruct an earlier frame from the final state of video memory. The resulting captures show the ATLUS logo and opening text referencing Zhuangzi's butterfly dream.

That matters because the project had spent a long time making progress that was mostly visible in CPU traces, BIOS calls, and test output. Seeing recognizable frames is a different kind of feedback.

The qualification is important: this is interpreter execution, not a successfully recompiled version of Persona. Reaching the title screen, playing the game, and matching this behavior in the generated native host remain unproven.

How the VBlank capture was implemented (PR #754)

A tiny PS1 executable can go all the way through recompilation

There is also now a reproducible showcase for the actual recompilation pipeline.

Using the released v0.0.0-alpha.2 CLI, a script generates an original five-instruction PS-X EXE, then follows this path:

Synthetic PS-X EXE
       |
       v
MIPS analysis and lowering
       |
       v
Generated host code
       |
       v
Native artifact build
       |
       v
Execute and inspect output

The demo prints P to the terminal. Real console captures document the result on Windows, and an equivalent released-binary run was verified on Linux.

Five instructions do not demonstrate compatibility with an entire commercial game. They do demonstrate that analysis, code generation, building, and execution can work together end to end for a controlled input.

Demo verification and screenshots (PR #781)

The hard part: two execution paths, different results

The biggest open problem is less photogenic.

The interpreter can advance through Persona's opening, but the standalone AOT + interpreter-fallback runtime still produces a black screen in the investigated scenario.

AOT means ahead-of-time compilation: known PS1 instructions are translated into host code before execution. When the generated host encounters a path it cannot handle, an interpreter can take over.

I am comparing the two execution paths instead of assuming the GPU renderer is responsible.

At one shared checkpoint, the recorded CPU state, RAM, VRAM, GPU state, captured device registers, and guest-cycle count match. That is equality at one checkpoint, not a claim that all preceding execution was identical. Their subsequent instruction paths diverge, and the root cause has not yet been identified.

One useful outcome of this investigation was finding a misleading diagnostic: a run stopped by an explicit request could be reported as if it had exhausted its instruction budget. The diagnostic was corrected, but the underlying rendering divergence is still open.

Investigation and measured limits (draft PR #787)

A concrete runtime optimization

On October 16, I merged a smaller, measurable change to the generated-host runtime.

The runtime was spending a lot of time exchanging synchronous messages between generated code and the host. In particular, a guest-time report was often sent immediately before an MMIO access.

Combining that time report with the MMIO request into one message reduced IPC round trips per guest instruction from 0.106 to 0.071, approximately 33% fewer in the measured setup.

A separate throughput measurement had a higher median, but considerable host noise, so I'm treating the round-trip reduction as the more reliable result.

This improves communication overhead; it does not establish that Persona now boots further or that the black-screen divergence is fixed.

IPC optimization and measurements (PR #796)

Tests should say what they actually tested

Another recent change was deliberately unglamorous: integration tests requiring real CHD files now skip explicitly when their input is unavailable, instead of silently returning and appearing to pass.

With a lawful local fixture present, the relevant tests can run normally. Without it, the test report distinguishes missing evidence from successful execution.

I want the project's status reports to keep three things separate: what a synthetic input proves, what a locally supplied real disc proves, and what has not been verified.

Real-ROM test reporting fix (PR #791)

What's next?

The immediate priority is to identify the first meaningful behavioral difference between interpreter and generated-host execution, then extend the runtime only with evidence for the missing behavior.

There is still substantial work ahead in BIOS and device behavior, recompiler coverage, runtime integration, and independent validation. A working demo and recognizable screenshots are milestones, not compatibility guarantees.

But I'm happy to have moved from “the traces are changing” to a project with visible frames, a reproducible native-code demo, a precise unsolved divergence, and measurements that can guide performance work.

If you work on emulators, recompilers, MIPS, or retro-game preservation, I'd be interested in technical feedback—especially on differential execution testing.

Repository: https://github.com/mao2009/PSXRecompStudio

The project does not distribute commercial game images, BIOS files, or copyrighted game data. Persona screenshots document interoperability research; the game and its imagery belong to their respective rights holders. PSXRecompStudio is unaffiliated with ATLUS.

Implementing 'You Can't' for AI Coding Agents

loach — Thu, 08 Oct 2026 03:28:21 +0000

AI coding agents are getting better at writing software. I use them in my own open-source projects, too.

But there's a distinction I keep coming back to:

Teaching an AI what it shouldn't do is not the same as enforcing what its code is allowed to do.

We ask agents not to break architectural boundaries, introduce side effects, or add unapproved dependencies. Those instructions are useful, but instructions are not guarantees.

Prompts aren't enforcement

Imagine an agent generates this code inside a Domain layer:

namespace MyApp.Domain;

public class OrderService
{
    private readonly Infrastructure.OrderRepository _repository;
}

If the referenced type exists, the C# compiler will not normally know that the dependency violates your architecture.

The code may work, compile, and still be unacceptable.

A README or AGENTS.md communicates a rule. It does not independently enforce it.

Move the decision outside the agent

The workflow I want looks like this:

AI agent or human writes code
             |
             v
      Compiler + Analyzers
             |
      Policy satisfied?
         /       \
       Yes        No
        |          |
   Candidate     Diagnostic
   for merge       |
                   v
                Revise code

The agent can propose a solution. An independent tool decides whether the proposal satisfies the project's checkable constraints.

For C# projects, Roslyn Analyzers let us report diagnostics during compilation. Configured as errors, those diagnostics can make a violating build fail.

This gives AI agents immediate, deterministic feedback rather than another natural-language reminder.

Three open-source projects exploring the approach

ArchitectureAnalyzer: Compile the architecture contract

ArchitectureAnalyzer uses a JSON architecture contract and Roslyn diagnostics to check rules such as layer dependencies, forbidden APIs, and dependency graph constraints.

An architecture document records intent. A machine-checkable contract helps detect drift between that intent and the codebase.

PureSharp: Enforce specific code-level contracts

PureSharp introduces functional-programming-oriented checks for C#.

For example:

[PureMethod]
public static int Add(int a, int b) => a + b;

It detects selected side effects within its documented purity contract. It also checks conventions for immutable local variables and FluentIf termination.

var _value = Calculate();
// _value = 100; // Diagnosed reassignment

This is not a whole-program mathematical proof of purity. It's enforcement of explicitly defined, mechanically checkable properties.

PolicySharp: Allow by policy, deny by default

PolicySharp takes an allowlist-oriented approach.

A denylist catches violations someone remembered to enumerate. A new API or dependency may not appear on that list.

A default-deny policy instead follows this model:

Explicitly allowed    -> ALLOW
Explicitly denied     -> DENY
Unknown or ambiguous  -> DENY

For example, a policy can describe which namespaces a Domain scope is allowed to depend on:

{
  "version": 1,
  "mode": "default-deny",
  "scopes": [
    {
      "id": "domain",
      "match": { "namespace": "MyApp.Domain.**" },
      "allow": {
        "namespaces": [
          "System",
          "MyApp.Domain.**"
        ]
      }
    }
  ]
}

This illustrates the policy model; precise enforcement coverage depends on the implemented version.

What if the agent changes the rules?

There's an obvious bypass:

The agent introduces a prohibited dependency.
An analyzer reports an error.
The agent edits the policy or project configuration.
The build passes.

That's why an analyzer alone isn't enough.

The authority to modify application code should be separate from the authority to weaken the constraints. Policy files, project files, and analyzer references may need independent approvals and CI checks.

Static analysis also has limits. It cannot enforce properties it does not analyze, and a build gate only matters when the project actually runs it.

Freedom to propose is not permission to merge

I don't want to constrain every implementation choice an AI makes.

I want to distinguish freedom to propose a solution from permission to accept the resulting change.

Within the approved boundaries, the agent can explore different approaches. If a boundary needs to change, that should become an explicit design decision instead of a workaround silently introduced during implementation.

Conclusion

Prompts communicate intent.

Analyzers enforce checkable rules.

CI validates changes.

Approval processes protect the rules themselves.

Instead of expecting AI to remember everything it must never do, we can create development environments that reliably detect prohibited changes before accepting them.

That is the direction I'm exploring with ArchitectureAnalyzer, PureSharp, and PolicySharp.

The goal isn't less capable AI. It's more predictable, maintainable AI-assisted software development.

Publishing .NET Packages to NuGet.org with an API Key

loach — Thu, 10 Sep 2026 12:00:55 +0000

Publishing a .NET library manually is fine once or twice, but it becomes tedious when releases are frequent or automated through CI/CD.

The standard solution is to push packages to NuGet.org with dotnet nuget push and an API key.

This article covers the basic flow and the most important security consideration: never commit the API key into the repository.

Prerequisites

You need:

a .NET project
a generated .nupkg file
a NuGet.org account

For example, your package might look like this:

./bin/Release/YourPackage.1.0.0.nupkg

Create a NuGet API key

When creating a new key, configure at least:

a recognizable key name
an expiration period
the Push scope
an optional package pattern if you want to restrict which packages the key can publish

The generated key should be treated like a password.

Do not put it in source code, scripts committed to Git, or Markdown examples containing a real value.

Push a package

The basic command is:

dotnet nuget push <PACKAGE_FILE> \
  --api-key <YOUR_API_KEY> \
  --source https://api.nuget.org/v3/index.json

For example:

dotnet nuget push ./bin/Release/YourPackage.1.0.0.nupkg \
  --api-key YOUR_API_KEY_HERE \
  --source https://api.nuget.org/v3/index.json

A useful option for CI is --skip-duplicate:

dotnet nuget push ./bin/Release/*.nupkg \
  --api-key "$NUGET_API_KEY" \
  --source https://api.nuget.org/v3/index.json \
  --skip-duplicate

This avoids failing a rerun just because the same package version was already published.

Store the key in GitHub Actions Secrets

For GitHub Actions, store the key as a repository secret, for example:

NUGET_API_KEY

Then reference it from the workflow:

- name: Publish package
  env:
    NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
  run: |
    dotnet nuget push ./bin/Release/*.nupkg \
      --api-key "$NUGET_API_KEY" \
      --source https://api.nuget.org/v3/index.json \
      --skip-duplicate

The API key stays outside the repository while still being available to the CI job.

Prefer narrow credentials

If the publishing key only needs to release one package family, restrict it to that package pattern where possible.

A narrow key reduces the impact if it is ever exposed.

The same principle applies to other CI credentials: give automation only the permissions it actually needs.

Closing thoughts

The mechanics of publishing a NuGet package are simple. The part worth designing carefully is credential handling.

A solid release flow usually looks like this:

build
  ↓
pack
  ↓
secret injected by CI
  ↓
dotnet nuget push

Keeping the credential out of the repository makes the process both automatable and reasonably safe.

PureSharp: Bringing Functional Safety to C# with Roslyn Analyzers

loach — Thu, 10 Sep 2026 11:55:44 +0000

C# is a very flexible language, but that flexibility also makes it easy for side effects and mutable state to spread through a codebase.

I built PureSharp to bring a few functional-programming ideas into everyday C# development and make them enforceable at compile time.

GitHub: https://github.com/mao2009/PureSharp

NuGet: https://www.nuget.org/packages/loach.PureSharp

What PureSharp tries to enforce

PureSharp focuses on three ideas:

Purity: methods explicitly marked as pure should not perform side effects.
Immutability: local variables can opt into a "do not reassign" convention.
Safer control flow: fluent conditional expressions should terminate explicitly.

The key point is that these rules are not just documentation. Roslyn analyzers report violations while you write and build the code.

Declaring a pure method

A method can be marked with [PureMethod]:

using PureSharp.Core;

public class Calculator
{
    [PureMethod]
    public int Add(int a, int b)
    {
        return a + b;
    }
}

Inside such a method, PureSharp can report operations that violate the declared purity contract, such as accessing mutable static state, calling methods that are not known to be pure, or performing I/O.

The goal is not to claim that every C# method can be proven mathematically pure. The goal is more practical: if a developer explicitly says "this method should be pure," the analyzer should help keep it that way.

Opt-in immutability for local variables

C# does not have a general-purpose const-style feature for local variables initialized at runtime.

PureSharp uses a naming convention: local variables beginning with _ are treated as non-reassignable.

public void ProcessData()
{
    int _result = CalculateValue();

    // Reported by the analyzer:
    // _result = 100;
}

This turns a simple convention into something the compiler can enforce.

The analyzer can also require immediate initialization and can suggest the immutable convention for locals that are never reassigned.

Fluent conditional expressions

PureSharp also provides Fluent.If, which makes it possible to use conditional branching as an expression:

int status = Fluent.If(score >= 80, () => 1)
    .ElseIf(score >= 60, () => 2)
    .Else(0);

The analyzer checks that a fluent chain is properly terminated with .Else().

The motivation is simple: if the construct is intended to produce a value, all paths should be explicit.

Why Roslyn analyzers?

These rules could be described in a style guide, but a style guide is only useful when someone remembers to enforce it.

Roslyn analyzers make the feedback immediate:

violations appear in the IDE
dotnet build can fail on violations
CI does not need a separate custom validator
rules stay close to the normal C# development workflow

That makes them especially useful for conventions that are easy to understand but tedious to police in code review.

Installation

Install the package from NuGet:

dotnet add package loach.PureSharp

After that, the analyzer participates in normal builds.

What I learned from building it

The interesting part of a tool like PureSharp is not the syntax of a single diagnostic. It is deciding where static analysis can give useful guarantees without pretending to understand more than it actually can.

C# remains an imperative, object-oriented language with many escape hatches. PureSharp is therefore intentionally opt-in: developers declare the rules they want, and the analyzer checks those declarations as far as static analysis reasonably allows.

That balance is what makes Roslyn analyzers attractive for this kind of developer tooling.

PureSharp is open source here:

https://github.com/mao2009/PureSharp

Using Ctrl+Enter to Submit in OpenCode and Enter for New Lines

loach — Thu, 10 Sep 2026 11:55:33 +0000

Another OpenCode behavior I wanted to change was message submission.

By default, pressing Enter submits the current prompt. If you are used to chat tools where Enter inserts a new line and Ctrl + Enter sends, this makes accidental submissions easy.

My preferred setup is:

Enter: insert a new line
Ctrl + Enter: submit the prompt

OpenCode configuration

Edit your OpenCode configuration file and update the keybindings:

{
  "keybinds": {
    "app_exit": "ctrl+d,<leader>q",
    "input_submit": "ctrl+return",
    "input_newline": "shift+return,return,alt+return,ctrl+j"
  }
}

This tells OpenCode to treat normal Enter-style keys as new lines and reserve Ctrl + Enter for submission.

The terminal may need configuration too

There is one important detail: some terminals do not send a distinct key sequence for Ctrl + Enter by default.

In that case, OpenCode cannot distinguish it from plain Enter.

For Windows Terminal, you can define a custom sequence:

"actions": [
  {
    "command": {
      "action": "sendInput",
      "input": "\u001b[13;5u"
    },
    "id": "User.sendInput.CtrlEnterCustom"
  }
]

Then bind Ctrl + Enter to that action in the terminal settings.

The exact terminal configuration can vary, but the principle is the same: the terminal must send a distinguishable sequence before OpenCode can bind it separately.

Why this improves the workflow

Long prompts often contain code blocks, lists, and multiple paragraphs.

Making Enter safe for editing removes the pressure to finish the whole prompt on one line and reduces accidental sends.

It also makes OpenCode behave more like many chat and editor-oriented interfaces.

Closing thoughts

Keybindings are a small detail, but AI coding tools are used interactively for long periods. Small interaction problems become surprisingly expensive when repeated all day.

For me, separating newline and submit made OpenCode much more comfortable to use.

Preventing Accidental OpenCode Exits with Ctrl+C

loach — Thu, 10 Sep 2026 11:50:23 +0000

OpenCode is powerful, but one default behavior kept getting in my way: pressing Ctrl + C could close the application itself.

If you spend a lot of time in terminals, Ctrl + C is muscle memory. You press it to interrupt a command, stop a long-running process, or simply because your hands move before you think.

Losing the whole OpenCode session because of that is frustrating.

The fix is simple: move the application exit action to a different keybinding.

Change the exit keybinding

Open your OpenCode configuration file and customize the keybindings.

For example:

{
  "keybinds": {
    "app_exit": "ctrl+d,<leader>q"
  }
}

With this configuration, Ctrl + C is no longer the application-exit shortcut.

You can then use Ctrl + D or the leader-based shortcut to exit intentionally.

Why this small change matters

AI coding agents often stay open for long sessions with valuable context.

A keybinding that is common for interruption in terminal workflows should not unexpectedly destroy that session.

Separating "interrupt what is happening" from "close the entire application" makes the interface much harder to use incorrectly.

Closing thoughts

This is a tiny configuration change, but it removed one of the most annoying sources of accidental session loss for me.

If you use OpenCode inside a terminal and frequently hit Ctrl + C out of habit, remapping app_exit is worth doing early.

Setting Up Japanese Input on Fedora KDE with Fcitx5 and Mozc

loach — Thu, 10 Sep 2026 11:50:12 +0000

After moving to Fedora KDE, one of the first things I wanted to fix was Japanese input.

My goal was not only to install Mozc, but also to make the conversion keys feel closer to what I was used to on macOS:

Henkan enables the IME
Muhenkan disables the IME

This article documents the setup I used with Fcitx5 + Mozc.

Install Fcitx5 and Mozc

On Fedora, install the required packages with:

sudo dnf install -y fcitx5-mozc fcitx5-configtool

Enable Fcitx5 in KDE

Open KDE System Settings and go to the keyboard / virtual keyboard settings.

Select Fcitx 5, or the Fcitx 5 Wayland launcher depending on your environment, and apply the change.

After logging out and back in, Fcitx5 should start as your input method framework.

Add Mozc

Open the Fcitx5 configuration tool:

fcitx5-configtool

Add Mozc to the list of available input methods.

If the keyboard layout is detected incorrectly, verify that the underlying keyboard layout matches your physical keyboard before adjusting IME shortcuts. Otherwise, a shortcut problem can actually be a layout problem.

Mac-like conversion key behavior

For Japanese keyboards, the Henkan and Muhenkan keys are convenient dedicated switches.

I configured them so that:

Henkan activates Japanese input
Muhenkan returns to direct input

This avoids using a single toggle key and makes the current IME state more predictable.

That small change made Fedora much more comfortable for daily development because I no longer had to wonder whether the next keystroke would be interpreted as Japanese or ASCII.

Why I prefer explicit on/off keys

Toggle shortcuts are compact, but they depend on remembering the current state.

Separate on/off shortcuts are more deterministic:

Henkan   -> IME ON
Muhenkan -> IME OFF

For programming, this is especially useful because switching from Japanese prose back to symbols, identifiers, and shell commands happens constantly.

Closing thoughts

Fcitx5 + Mozc works well on Fedora KDE once the desktop integration and keyboard shortcuts are configured.

The installation itself is simple; the quality-of-life improvement comes from tuning the input method to your keyboard habits.

If you are moving from macOS or another environment where dedicated IME on/off keys are part of your muscle memory, mapping Henkan and Muhenkan explicitly is worth trying.

Keeping Translated OSS Documentation Fresh with an SSOT and CI

loach — Thu, 10 Sep 2026 11:11:01 +0000

Publishing an OSS project in multiple languages is useful, but translated documentation introduces a maintenance problem very quickly.

Typical failure modes are familiar:

the English README changes but the Japanese version does not
nobody is sure which version is authoritative
a translation gains content that never reaches the canonical document
developers or AI tools read an outdated translation as if it were current design documentation

I ran into this while expanding the English documentation for PSXRecompStudio.

GitHub: https://github.com/mao2009/PSXRecompStudio

My solution was to make the English documents the explicit canonical source / SSOT and add CI checks that detect stale translations.

Why translations need a source of truth

Suppose a repository has:

README.md
README.ja.md

If both files are treated as equally authoritative, every edit creates a coordination problem.

Instead, I use a simpler rule:

English is canonical. Translations are derived documents.

A translated document is still valuable for readers, but architectural and specification decisions ultimately refer back to the canonical file.

Store the relationship as data

The canonical-to-translation mapping is kept in JSON rather than hard-coded into the CI script.

For example:

{
  "version": 1,
  "pairs": [
    {
      "canonical": "README.md",
      "translation": "README.ja.md",
      "language": "ja",
      "canonicalMarker": "[English README (Canonical / SSOT)](README.md)"
    }
  ]
}

This describes which file is authoritative, which file is its translation, the language, and which canonical marker should appear in the translation.

As the documentation set grows, adding a new pair is a data change rather than a code change.

Make the canonical relationship visible to humans too

The translated document should clearly say that it is a translation and link back to the canonical source.

That helps in two ways:

readers know which file wins when there is disagreement
CI can verify that the relationship is still declared

This avoids a common documentation smell: two almost-identical files with no explicit indication of which one is authoritative.

Detect stale translations in CI

The next step is to make freshness machine-checkable.

A practical approach is to record which canonical revision a translation was last synchronized against. CI can then compare that information with the current canonical file.

Conceptually:

canonical changed
      ↓
translation metadata still points to old revision
      ↓
CI reports stale translation

The exact implementation can vary. The important part is that freshness becomes a build-time property instead of something maintainers have to remember manually.

Why this matters for AI-assisted development

Outdated translations are especially dangerous when repositories are consumed by AI coding agents.

A human may notice that a translated document looks old. An agent may simply treat the first relevant file it finds as the current specification.

By declaring one SSOT and checking synchronization automatically, the repository gives both humans and tools a clearer hierarchy of trust.

Treat documentation like code

The broader lesson is that documentation maintenance benefits from the same ideas we already use for source code:

define ownership
define the source of truth
represent relationships in machine-readable form
validate invariants in CI
fail visibly when derived artifacts become stale

Translations are derived artifacts, even when humans maintain them manually.

Once I started treating them that way, the maintenance model became much clearer.

Closing thoughts

Multilingual OSS documentation is valuable, but duplicating information without an explicit authority model creates ambiguity.

Making one language canonical and validating translation freshness in CI gives the repository a predictable rule:

translations may lag temporarily, but they cannot silently pretend to be current.

That small distinction makes documentation easier to maintain and safer to consume.

Enforcing C# Architecture Rules at Compile Time with a Roslyn Analyzer

loach — Thu, 10 Sep 2026 11:01:55 +0000

When a C# project adopts layered architecture or Clean Architecture, we often define rules such as:

the Domain layer must not depend on the Application layer
the Domain layer must not call I/O APIs such as Console or File directly
interop entry points must stay inside a specific boundary

The problem is that rules written only in README files, ADRs, or design documents are still easy to violate.

A review can miss a dependency. A temporary shortcut can become permanent. Over time, the implementation slowly drifts away from the architecture described in the documentation.

To make these rules executable, I built ArchitectureAnalyzer, a Roslyn Analyzer that validates architecture rules during normal C# compilation.

GitHub: https://github.com/mao2009/ArchitectureAnalyzer

Project site: https://mao2009.github.io/ArchitectureAnalyzer/

Define the architecture as data

ArchitectureAnalyzer keeps project-specific rules outside the analyzer itself. They live in an architecture.contract.json file.

For example:

{
  "layers": [
    {
      "name": "Domain",
      "namespaceRoots": ["MyApp.Domain"]
    },
    {
      "name": "Application",
      "namespaceRoots": ["MyApp.Application"]
    }
  ],
  "forbiddenDependencies": [
    {
      "from": "Domain",
      "to": "Application",
      "reason": "Domain must not depend on the outer Application layer."
    }
  ]
}

With this contract, any type below MyApp.Domain is classified as Domain and any type below MyApp.Application as Application.

If Domain references Application, the build fails with a Roslyn diagnostic such as:

error AARC002: 'MyApp.Domain.Order' (Domain) must not depend on
'MyApp.Application.OrderService' (Application):
Domain must not depend on the outer Application layer.

This means the compiler catches the violation before a human reviewer has to.

Forbidden APIs

Architecture rules are not limited to layer-to-layer dependencies.

You can also block specific APIs from a layer. For example, to keep console I/O out of Domain:

{
  "forbiddenApis": [
    {
      "layer": "Domain",
      "type": "System.Console",
      "reason": "Console I/O must be abstracted behind an Infrastructure adapter."
    }
  ]
}

Then code like this can be rejected at compile time:

namespace MyApp.Domain;

public class Order
{
    public void Print()
    {
        Console.WriteLine("Order");
    }
}

Why JSON instead of hard-coded rules?

Different projects use different architectures. Hard-coding Domain, Application, and Infrastructure into the analyzer would make it project-specific.

Instead, ArchitectureAnalyzer follows a simple split:

The analyzer implements the mechanism. The project defines the policy.

That also means architecture rules can be reviewed and versioned in Git like source code.

Attribute-based layer declarations

Version 0.1.0 also supports explicit layer markers using attributes.

A contract can map attributes to layers:

{
  "layerDeclaration": {
    "required": true,
    "markerAttributes": [
      {
        "attributeFqn": "MyApp.Architecture.DomainAttribute",
        "layer": "Domain"
      },
      {
        "attributeFqn": "MyApp.Architecture.ApplicationAttribute",
        "layer": "Application"
      }
    ],
    "validateNamespaceConsistency": true,
    "markerNamespace": "MyApp.Architecture"
  }
}

Then a type can declare its architectural role directly:

using MyApp.Architecture;

namespace MyApp.Domain;

[Domain]
public class Order
{
}

When namespace and attribute declarations disagree, the analyzer can report the mismatch.

This is useful when you want architecture to be visible both from project structure and directly in code.

Why a Roslyn Analyzer?

The same validation could be implemented as a custom CLI or CI script, but a Roslyn Analyzer has an important advantage: it becomes part of the normal development loop.

You get diagnostics in the IDE, during dotnet build, and in CI without teaching developers a separate command.

Install the package and provide the contract as an additional file:

<ItemGroup>
  <PackageReference Include="loach.ArchitectureAnalyzer"
                    Version="0.1.0"
                    PrivateAssets="all" />
  <AdditionalFiles Include="architecture.contract.json" />
</ItemGroup>

Then the normal build is enough:

dotnet build

The same command naturally becomes a CI architecture gate.

What it does not do

ArchitectureAnalyzer does not decide whether your architecture is good.

It only answers a narrower question:

Does the implementation still obey the architecture rules this project explicitly defined?

Reflection, dynamic, generated code that is excluded from analysis, and some indirect access patterns are outside the guarantees of a normal static analyzer.

That limitation is intentional. The tool is designed to prevent architecture drift, not to replace architectural design.

Closing thoughts

Architecture documentation is valuable, but documentation alone cannot stop code from drifting away from it.

By moving the rules into a machine-readable contract and validating them during compilation, architecture becomes something the build can enforce rather than something reviewers merely have to remember.

ArchitectureAnalyzer is open source, and the project is available here:

https://github.com/mao2009/ArchitectureAnalyzer