asm 0.5.0

asm 0.5.0

Version 0.5.0 adds inventory, upgrade, and uninstall commands for programs installed through Asm.
Published 0.4.0 artifacts remain unchanged and do not include these commands.

Host contract

Host	CLI artifact	Native project target
Linux x86-64	asm-0.5.0-x86_64-linux	x86_64-linux
Linux ARM64	asm-0.5.0-aarch64-linux	aarch64-linux
Apple Silicon, macOS 15 or later	asm-0.5.0-aarch64-macos	aarch64-macos

ISA means instruction set architecture. ABI means application binary interface.
The operating system, ABI, and CPU requirements are separate requirements.

CLI target	ISA	Operating system	ABI and executable format	CPU requirements
x86_64-linux	x86-64	Linux	Linux x86-64 system calls; little-endian ELF64	No optional CPU features declared.
aarch64-linux	AArch64	Linux	Linux AArch64 system calls; little-endian ELF64	ARMv8-A; no optional CPU features declared.
aarch64-macos	AArch64 (arm64)	macOS 15 or later	Apple arm64, Mach-O, and libSystem	Apple Silicon; no optional CPU features declared.

The Linux native CI runners use Ubuntu 24.04.
A minimum Linux kernel version has not been qualified separately.

Intel macOS, Windows x86-64, Windows ARM64, and a native Linux RISC-V64 CLI are not included.
The Linux RISC-V hello example does not establish native CLI support.
Project builds require GNU Binutils on Linux or Xcode Command Line Tools on macOS.

Manage installed programs

On Linux x86-64 or ARM64, install the hello executable:

asm install stubbi/hello@0.5.0

The default destination is $HOME/.local/bin/hello.
Use --output PATH to select another new destination.
Asm records both default and explicit destinations in $HOME/.local/state/asm/installed.tsv.
Each record contains the package, version, host target, digest, size, absolute path, and registry origin.
One package identity has at most one managed installation.

List recorded installations:

asm installed
asm installed --json

Listing reads the inventory without network access.
It does not verify that current executable files still match their records.
An empty JSON inventory is {"installed":[]}.

Upgrade a recorded program:

asm upgrade stubbi/hello

Upgrade selects the highest available numeric version for the host.
Use owner/name@version to select an exact version.
It retains the recorded destination and HTTPS registry origin.
Local-index installations require --index PATH again.
Upgrade rejects an older version, another registry origin, or changed bytes for an equal version.

Uninstall a recorded program:

asm uninstall stubbi/hello

Uninstall removes the recorded executable and its inventory entry.
It leaves the destination directory and other package data.
Install, upgrade, and uninstall do not execute the program.
They are quiet on success unless --json is supplied.

The commands update and remove continue to manage project source dependencies.
Use asm self update to update Asm itself.
The $HOME/.local/bin/asm destination and case variants remain reserved for that route.

File protection and recovery

Upgrade and uninstall check the recorded size and SHA-256 digest before changing a file.
They require a user-owned, single-link regular executable with protected permissions.
They refuse changed files, symlinks, malformed inventory records, and unmanaged destinations.

Programs installed before 0.5.0 have no inventory record.
Updating Asm does not adopt them, even when their names and bytes match a package.

Destination checks use the filesystem's filename rules, including case and Unicode aliases.
A temporary, empty destination with mode 000 protects recorded names during this check.
Cleanup removes it only when it still matches the owned probe.
Interruption or a cleanup failure can retain it for manual inspection.

Private staging and an advisory lock coordinate Asm operations.
Ordinary commit failures restore the prior executable and retain the prior inventory.
The lock does not constrain another process that runs under the same account.

The executable and inventory use separate filesystem entries.
Their updates are not one atomic transaction.
Process interruption or power failure can require manual recovery of staged files or mismatched records.
Retain those files for inspection; automatic crash recovery is not provided.
See the installed-program contract for the format, file boundaries, and recovery requirements.

Other changes

• Core commands return a nonzero exit status when their output cannot be written.
• Committed-source packaging and published-history checks ignore local Git object replacements.
• Source collectors check the aggregate byte limit before reading each file.
• Repository documentation clarifies the layout, reference manifest, host support, and retained performance measurements.

The source includes a disabled bundled-verifier profile for signed update authorization and release provenance.
Production activation still requires offline keys, metadata renewal, review, and recovery qualification.
This release retains the GitHub CLI 2.93.0-or-later installation and self-update contract.
See the migration gates and self-update contract.

Release evidence and limits

The release workflow requires native command tests and identical bytes from two clean builds for each CLI host.
It binds release artifacts to an exact source commit, sizes, digests, and GitHub release-provenance evidence.
Publication requires the workflow's validation of those final bytes.
This document does not record a completed release run.

Package integrity checks use the selected index's sizes and digests.
They do not establish publisher identity, registry freshness, or that a program is harmless.
The registry still has no separately signed expiry, rollback protection, or implemented emergency-revocation service.
Hosted public builds and formal verification remain planned.
See the security model for the full trust boundaries.

ASM 0.4.0

ASM 0.4.0

This candidate adds a native Apple Silicon macOS CLI.
Publication requires the protected checks, native qualification, and verified release-workflow provenance.
Published 0.3.0 artifacts remain unchanged.

Host contract

Host	CLI artifact	Native project target
Linux x86-64	asm-0.4.0-x86_64-linux	x86_64-linux
Linux ARM64	asm-0.4.0-aarch64-linux	aarch64-linux
Apple Silicon, macOS 15 or later	asm-0.4.0-aarch64-macos	aarch64-macos

The macOS command is native arm64 assembly linked with libSystem.
It does not execute a Linux binary or use Rosetta.
Intel macOS remains unsupported.

Installation and update

After publication and the checked catalog update, the single installer selects the exact operating system and ISA.
The command remains:

curl -qfsS -m120 https://asm.build/install.sh | sh

On macOS, install GitHub CLI 2.93.0 or later at /opt/homebrew/bin/gh first.
The bootstrap uses macOS system tools, including Perl for bounded verifier execution.
It does not require GNU Coreutils, administrator access, or a GitHub login.
Project builds require Apple's Xcode Command Line Tools.

Installation and self-update require a protected local APFS path with ownership enabled.
ACL allow entries are refused; normal deny-only home ACLs remain supported.
The updater compares the executing vnode and destination before atomic replacement.
It preserves installed bytes after failed downloads, integrity checks, attestations, or file checks.

The macOS feed is /registry/v1/index-macos.tsv.
The existing Linux feed omits macOS rows so released 0.3.0 clients can still select their next update.
Both feeds retain the existing limits, including absent signed expiry and rollback protection.

Evidence and limits

Native CI builds the macOS CLI twice from the same recorded commit.
It requires identical bytes and successful native command and hostile-input tests.
Release publication includes those final bytes in the required GitHub provenance attestation.
The release job verifies artifact size, digest, workflow, repository identity, source, signer, and hosted-runner policy.

The Mach-O code signature is ad-hoc.
Publisher authentication comes from the separately verified GitHub release provenance.
Developer ID signing and Apple notarization are not provided.
Do not disable Gatekeeper as an installation step.

Tests using local transport and verifier fixtures do not claim Sigstore cryptographic verification.
The release workflow performs that separate verification before publication.
See the macOS qualification contract and update security contract.

ASM 0.3.0

ASM 0.3.0

ASM now has native assembly clients for Linux x86-64 and ARM64.
One installer selects the correct published executable for either host.
The release also reduces the work required to validate and print large local catalogs.

Install

Install curl, GNU Coreutils, and GitHub CLI 2.93.0 or later in /usr/bin.
The verifier does not need a GitHub login.
Run:

curl -qfsS -m120 https://asm.build/install.sh | sh

The installer reads the host with uname.
It binds that target to a fixed release URL, byte size, and SHA-256 digest.
It verifies the signed release before installing $HOME/.local/bin/asm.
An unsupported operating system or architecture stops installation before downloads or file changes.

The command uses the canonical HTTPS address without following redirects.
It disables curl startup configuration, rejects HTTP errors, shows failures, and limits the transfer to 120 seconds.
The README also provides inspection and complete-download commands for CI.

For an existing supported installation, run:

asm self update

Each client selects its own host artifact.
The downloaded command is never executed during installation or self-update.

Native host support

Host	Executable	Project build target
Linux x86-64	asm-0.3.0-x86_64-linux	x86_64-linux
Linux ARM64	asm-0.3.0-aarch64-linux	aarch64-linux

Both implementations use native assembly and direct Linux system calls.
The ARM64 implementation uses baseline ARMv8-A instructions.
The implementation notes describe its internal calling convention and Linux ABI boundary.

Both clients provide project creation, builds, execution, tests, registry commands, direct dependencies, publication preparation, and manual self-update.
asm new creates source and a manifest for the running host.
asm targets reports that native project target.

A client can fetch artifacts for other package targets.
General cross-build commands remain future work.
The RISC-V hello package remains available, but this release does not include a RISC-V CLI.
macOS and Windows hosts remain unsupported.

The source archive contains both CLI implementations.
Use make to select the native implementation.
The archive's root asm.toml still describes the x86-64 reference project.
Its registry source artifact is therefore labeled x86-64; it is not a falsely labeled ARM64 source package.

Registry performance

Catalog validation now uses heap sort over a separate array of record pointers.
It checks duplicate artifact identities in bounded O(n log n) work.
The input order remains unchanged.
A 64 KiB buffer reduces output system calls.
Output failures return a nonzero exit status.

On one measured x86-64 host, 4,096-record local searches had approximately 19–21 times lower median elapsed time.
The experiment compares the previous registry implementation with the changed implementation while keeping other CLI modules identical.
Small-catalog wall-time results were inconclusive, and some tail latencies increased.

Read the complete performance record for exact executable identities, hardware, methods, raw samples, and regressions.
These results do not measure ARM64 performance, network installation, or service capacity.

Release checks

CI runs the CLI contract suite on native x86-64 and ARM64 runners.
Both native jobs are required before publication.
The release builder compares two clean builds for each executable.
It checks the cross-built ARM64 version and target output through QEMU.
Emulation complements the native tests; it does not establish native performance.

The release contains source, SHA256SUMS, release.json, and the signed provenance bundle.
The source archive includes the benchmark evidence.
Bootstrap installation and self-update bind the selected executable to its exact source commit and release workflow.

Remaining limits

• Dependencies use exact direct versions. There is no transitive resolver or version-range syntax.
• Publication uses reviewed registry records. asm publish prepares a local submission.
• The index has no independently signed expiry or revocation record.
• Download observations count GitHub asset requests, not unique users or installations.
• Hosted proof checks, public build workers, and ownership recovery remain future work.
• The assembly server experiment remains separate from the deployed website.

ASM remains an alpha.
Read the security model and self-update contract before relying on their guarantees.
ASM uses AGPL-3.0-or-later; starter text and reference examples retain their MIT grants.
Earlier release bytes and licenses remain unchanged.

ASM 0.2.0

ASM 0.2.0

This alpha connects a native assembly CLI to a public assembly package registry.
It supports Linux x86-64 hosts.
Package records can include x86-64, AArch64, and RISC-V Linux artifacts.

License policy

ASM now uses AGPL-3.0-or-later.
Starter text and the reference examples retain their MIT licenses.
Independent packages retain the license declared for each version.
Run asm license for the license, source location, and warranty notice.
Read the license scope before modifying or distributing ASM.

Version 0.1.0 was published under MIT.
This release does not change that historical license.

Start a project

Install GNU Binutils, curl, GNU Coreutils, and gzip.
Binary installation and manual updates also need GitHub CLI 2.93.0 or later.
No GitHub login is required.
The source build also needs Git and GNU Make.
Follow the installation instructions.

asm doctor
asm new hello
cd hello
asm run
asm test

The program prints Hello from asm!.

What this release includes

• A Linux x86-64 CLI written in assembly, with direct system calls.
• A bootstrap installer that verifies the signed release before installation.
• Native asm self update for manual, provenance-verified updates from the hub.
• Project creation, builds, execution, tests, and cleanup.
• Package search, version lists, artifact downloads, and executable installation.
• Exact direct source dependencies, asm.lock, cache verification, and synchronization.
• Native preparation of a publication record for a reviewed pull request.
• A public catalog with targets, versions, source commits, evidence states, and download observations.
• Commit-bound source archives and a browsable CLI source reference at asm.build.

The registry starts with three reference packages:

Package	Purpose	Targets
stubbi/asm	The CLI and its source.	x86-64 Linux
stubbi/hello	A complete first project.	x86-64, AArch64, and RISC-V Linux
stubbi/math	A small source dependency with an explicit function contract.	x86-64 Linux

Release evidence

SHA256SUMS identifies the release files.
release.json records the source commit, tool versions, build commands, and execution results.
The release job compares two clean builds and deterministic source archives.

The x86-64 examples run natively.
The cross-target examples run through QEMU.
Emulation does not establish performance or compatibility on every physical processor.

The release workflow creates and verifies GitHub provenance attestations for each published artifact.
Verification checks the repository, workflow identity, source commit, workflow commit, and runner environment.
Check the workflow result and the attestation for the exact digest before relying on that claim.
The published release-attestation.sigstore.json contains the action-produced signature bundle.
Bootstrap installation and asm self update verify that bundle with the fixed release policy.
General package downloads still check registry digests; they do not inherit the CLI release's provenance result.

Integrity and failure behavior

Downloads must match both their declared size and SHA-256 digest.
Install checks the ELF target and segment bounds.
Source extraction rejects unsafe paths, links, special files, ambiguous members, and resource-limit violations.
Existing destination files remain intact when an operation fails.

Dependency commands use exact versions.
The lock file records the target, artifact URL, size, digest, and registry origin.
Builds check locked archives and extracted source trees before assembly.
The assembler can still read other local files through explicit includes.
A lock file is not a build sandbox.

Known limits

This is an alpha, with a deliberately stated support boundary.

• The native CLI host and project build target are Linux x86-64.
• Dependencies are direct and exact. There is no transitive resolver or version-range syntax.
• Publication uses maintainer review. asm publish prepares a local record; it does not upload or reserve a name.
• The HTTPS registry is the digest authority. Separate signed metadata and rollback protection are future work.
• Download counts are GitHub asset requests, not unique users or installations.
• Formal proofs, vulnerability analysis, and agent review are separate proposed services.
• Self-update is manual and limited to the direct user-owned $HOME/.local/bin/asm installation.
• Self-service ownership recovery and isolated public build workers remain future work.

Read the security model before running package code.
Report defects through GitHub Issues.
Use private vulnerability reporting for a security defect.

Why ASM

We expect AI to make useful assembly cheaper to produce and maintain.
Reliable reuse then needs common package formats, explicit targets, and inspectable evidence.
That expectation guides the project; experiments must still support each performance, correctness, and cost claim.

Read the working assumptions.

ASM 0.1.0

ASM 0.1.0

The first alpha connects a native assembly CLI to a public assembly package registry.
It supports Linux x86-64 hosts.
Package records can include x86-64, AArch64, and RISC-V Linux artifacts.

Start a project

Install GNU Binutils, curl, GNU Coreutils, and gzip.
The source build also needs Git and GNU Make.
Follow the installation instructions.

asm doctor
asm new hello
cd hello
asm run
asm test

The program prints Hello from asm!.

What this release includes

• A Linux x86-64 CLI written in assembly, with direct system calls.
• Project creation, builds, execution, tests, and cleanup.
• Package search, version lists, artifact downloads, and executable installation.
• Exact direct source dependencies, asm.lock, cache verification, and synchronization.
• Native preparation of a publication record for a reviewed pull request.
• A public catalog with targets, versions, source commits, evidence states, and download observations.
• Commit-bound source archives and a browsable CLI source reference at asm.build.

The registry starts with three reference packages:

Package	Purpose	Targets
stubbi/asm	The CLI and its source.	x86-64 Linux
stubbi/hello	A complete first project.	x86-64, AArch64, and RISC-V Linux
stubbi/math	A small source dependency with an explicit function contract.	x86-64 Linux

Release evidence

SHA256SUMS identifies the release files.
release.json records the source commit, tool versions, build commands, and execution results.
The release job compares two clean builds and deterministic source archives.

The x86-64 examples run natively.
The cross-target examples run through QEMU.
Emulation does not establish performance or compatibility on every physical processor.

The release workflow requests GitHub provenance attestations for the published artifacts.
Check the workflow result and the attestation for the exact digest before relying on that claim.
The current CLI checks the registry digest; it does not verify attestations itself.

Integrity and failure behavior

Downloads must match both their declared size and SHA-256 digest.
Install checks the ELF target and segment bounds.
Source extraction rejects unsafe paths, links, special files, ambiguous members, and resource-limit violations.
Existing destination files remain intact when an operation fails.

Dependency commands use exact versions.
The lock file records the target, artifact URL, size, digest, and registry origin.
Builds check locked archives and extracted source trees before assembly.
The assembler can still read other local files through explicit includes.
A lock file is not a build sandbox.

Known limits

This is an alpha, with a deliberately stated support boundary.

• The native CLI host and project build target are Linux x86-64.
• Dependencies are direct and exact. There is no transitive resolver or version-range syntax.
• Publication uses maintainer review. asm publish prepares a local record; it does not upload or reserve a name.
• The HTTPS registry is the digest authority. Separate signed metadata and rollback protection are future work.
• Download counts are GitHub asset requests, not unique users or installations.
• Formal proofs, vulnerability analysis, and agent review are separate proposed services.
• There is no self-update command, self-service ownership recovery, or isolated public build service.

Read the security model before running package code.
Report defects through GitHub Issues.
Use private vulnerability reporting for a security defect.

Why ASM

We expect AI to make useful assembly cheaper to produce and maintain.
Reliable reuse then needs common package formats, explicit targets, and inspectable evidence.
That expectation guides the project; experiments must still support each performance, correctness, and cost claim.

Read the working assumptions.