 |
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
|
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
The workflows on feature/libmemalloc-refactor derive from Coil's workflows. Local actions, configuration, and Lua checks are stored in this repository; workflow execution does not depend on a moving Coil branch.
| Layer | Responsibility | Implemented scope |
|---|---|---|
| Lua | Apply policies, plan work, execute tools and validate results. | Existing CI and release scripts; local process pilot. |
| Ansible | Prepare hosts and coordinate Lua commands. | Localhost preparation and delegation to the four-control Lua campaign. |
| GitHub Actions | Supply events, runners, permissions and artifact transport. | Workflows listed in the catalog. |
Keep acceptance logic and matrices in Lua. Contributors can invoke Lua without Ansible. The process pilot has four registered verifiers and accepts only local. The reusable lint workflow invokes its process-ci campaign and retains the requirement evidence graph. Qualified host preparation, remote campaigns and protected promotion remain listed in the gapregister.
See the workflow catalog for entry points, execution environments and coverage.
Pushes and pull requests target all branches, including the refactor branch. Merge queues, manual runs, tags, the default branch, and releases receive full validation. Other changes select checks by path. REUSE always runs. Scheduled security checks run weekly on the default branch. Local documentation links are checked on every selected run. External links are checked on the default branch, manual runs, and releases.
Third-party actions use commit SHAs. Downloaded tools use versions and digests from tools/toolchain/lock.toml. Dependency installation disables lifecycle scripts where supported. Validation permissions are read-only, and checkouts do not retain credentials. Pull requests and merge queues use GitHub-hosted runners. The protected signing job has OIDC authority; publication jobs use scoped credentials.
Repository scripts use Lua. A system Lua 5.4 interpreter bootstraps the lock reader; subsequent checks use the pinned Lua runtime. Python-based third-party tools such as REUSE and yamllint run in isolated environments. The C and Lua metrics adapters in tools/analysis/ use locked Python analysis APIs under Lua controllers. The Lua quality gate documents shared complexity limits, counting conventions and retained evidence. The Conan recipe remains a native packaging interface.
Follow the local checks runbook. Its commands require an indexed checkout and the declared tools. They cover local checks; hosted events and platform campaigns have separate entry points.
LIBMEMALLOC_CI_RUNNER optionally selects a runner for trusted events. Cache services are optional; see the cache configuration. Keep private runners limited to branches whose contributors can run trusted code. The workflows work without external cache credentials.
Set LIBMEMALLOC_REQUIRE_SIGNED_COMMITS=true to require GitHub-verified OpenPGP commit signatures. This supplements the existing signature guide; DCO is always checked. Scope and body remain optional, as specified by the commit guide. The Coil hooks are not installed or used because their message policy differs.
Configure branch protection to require CI gate, the security jobs, and Commit policy. GitHub settings are not changed by these files. Renovate proposes updates against the refactor branch; its scheduled workflow must reach the default branch to execute. Dependabot version updates are disabled to avoid duplicates. Configure the protected environments and secrets listed in the release fixture guide. Tool and npm dependency updates must keep the lock and package files in sync.
Publishing a release triggers validation once through the published event. Only successful validation produces an Actions artifact using a deterministic source-packaging recipe and checksum manifest, retained for 30 days. Independent reconstruction is not checked by this job. This workflow does not create releases, upload release assets, or deploy a website or container.
This branch contains a Lua-driven C release fixture, not an allocator implementation. The current C jobs validate policies, the fixture, and documentation examples. The platform matrix and batched semantic qualification execute the mock across languages, toolchains and flags. Allocator-specific properties and coverage remain pending the implementation. The old Docker and Pages jobs depend on removed build scripts and are not runnable in this tree.
The module gate uses the compiler-backed mock subset described in the campaign guide. LIBMEMALLOC_MODULE_CHECKER can override it with a qualified external checker. The current checks do not enforce every C-guide rule.
Class: SECURITY. Obligation: project requirement.
Start workflows with permissions: {} and grant each job only the permissions it uses. Current validation uses contents: read; checkout disables persistent credentials. Third-party actions use full commit pins.
Pull requests and merge groups use GitHub-hosted runners. The optional LIBMEMALLOC_CI_RUNNER setting applies to other events; a push to an untrusted branch is not safe merely because it is a push. Restrict access before choosing a private runner, and do not expose signing credentials or private networks to it.
Pass event fields through environment variables and quote them. Never interpolate pull-request text into executable shell source. Do not check out and execute untrusted code in a privileged pull_request_target or workflow_run context.
flowchart LR
PR[Untrusted pull-request source] --> Hosted[GitHub-hosted validation]
Hosted --> Findings[Logs and findings]
Trusted[Reviewed source and protected event] --> Qualified[Qualified release inputs]
Qualified --> Promotion[Future protected promotion job]
Promotion --> Signing[Separate signing authority]
PR -. No credentials or automatic artifact promotion .-> Boundary[Trust boundary]
Class: GOVERNANCE. Obligation: project requirement.
The commit validator enforces the local commit guide: Conventional Commits, 70-character lines, and DCO trailers. Scope and body remain optional. The LIBMEMALLOC_REQUIRE_SIGNED_COMMITS setting adds GitHub-verified OpenPGP checking; do not describe that option as enabled without inspecting the repository setting.
REUSE validates license metadata. Preserve imported attribution. Repository-wide annotations do not by themselves demonstrate every per-source-file licensing criterion of the OpenSSF Gold plan.
Class: SECURITY. Obligation: project requirement.
The security workflow runs zizmor and dependency auditing, scans history with Gitleaks, and checks gittuf metadata when present. Its optional gittuf mode is not an adopted mandatory signing policy. Scheduled security runs use the default branch and must be investigated when they fail.
The published release event starts fresh CI, security, and commit validation. The source job waits for all three. It validates the tag format, source identity, and clean checkout, then packages source and a checksum manifest as an Actions artifact retained for 30 days. It does not upload release assets or sign them. Because the event follows publication, it cannot prevent the initial publication of the GitHub release itself. A future promotion gate must run before distribution.
The implemented fixture adds two clean same-host mock builds, dual SBOMs, subject-bound test logs, and local provenance statements. The protected signing job creates and verifies Sigstore bundles after the gates. An authorized prerelease can publish libmemalloc-mock to a configured Conan test remote. These jobs do not qualify production allocator releases or SLSA L3. Use the OpenSSF adoption stages for the remaining governance, scanner, isolated-builder, and distribution requirements.
flowchart TD
Published[GitHub release already published] --> CI[Fresh CI]
Published --> Security[Security workflow]
Published --> Commits[Commit policy]
CI --> Source[Source job waits for all three]
Security --> Source
Commits --> Source
Source --> Identity[Validate tag / commit / clean checkout]
Identity --> Package[Source archive and checksum manifest]
Package --> Artifact[Actions artifact: 30-day retention]
CI --> Fixture[Verified mock tree from CI]
Artifact --> Sign[Protected mock signing]
Fixture --> Sign
Sign --> Verify[Verify identity and artifact subjects]
Verify --> Signed[Signed fixture Actions artifact]
Signed --> Conan[Conan test channel: authorized prereleases only]
Class: CHANGE_CONTROL. Obligation: project requirement.
A pipeline change must update affected fixtures, locks, documentation, and indexes. Run positive and negative policy tests, validate Actions syntax and security, and exercise changed scripts locally. Explain checks that require hosted events, external credentials, or a native target and could not be run locally.
Do not register services, change repository protection, publish artifacts, or claim a badge as a side effect of editing these guides. Those actions require maintainer authorization and evidence from the actual repository configuration.
Class: PROJECT_POLICY. Obligation: project requirement.
The executable configuration is under .github/workflows. These reference pages explain its contract; changes to the configuration must update the contract and tests together. Use the workflow catalog for the workflow inventory. Controls marked as requirements for future product jobs do not imply those jobs exist.
The semantic qualification graph runs in GitHub Actions and qualifies the implemented mock across optimization, PGO, compiler boundaries and independent reconstruction. It is required by CI gate. Pending allocator contracts remain explicit and cannot inherit the mock's successful result.
There is no allocator build or supported-platform release matrix in this tree yet. The C gates exercise policy fixtures, the release mock, and complete C-guide examples. The proposed SDD laboratory, Rust implementation, GC, performance campaigns, and product coverage gates have not been implemented by those checks.
The CI contract lives with the reference for each concern. Preserve its CICD-* identifiers when editing implementation, policy or evidence requirements. These controls describe the existing automation and its declared limits; they do not qualify the planned allocator.
| Control | Canonical reference |
|---|---|
| CICD-001 | Events and selection |
| CICD-002 | Required results |
| CICD-003 | Execution authority |
| CICD-004 | Tools and dependencies |
| CICD-005 | Source and documentation checks |
| CICD-006 | Spelling, prose, and references |
| CICD-007 | C evidence |
| CICD-008 | Cache trust |
| CICD-009 | Commit and license policy |
| CICD-010 | Security and release |
| CICD-011 | Failure and evidence handling |
| CICD-012 | Changes to the pipeline |
The engineering change category selects release-contract, qualification and reproducibility campaigns for changes to source, build, packaging, automation, tests, tools or workflows. Trusted integration and release events force all categories. The CI gate requires success for selected campaigns and an explicit skip for unselected ones. Documentation-only changes retain their documentation and language checks without scheduling unrelated release qualification.
tools/testing/suites.lua lists executable automation suites and identifies fixtures owned by domain campaigns. The automation runner rejects missing or unregistered tests. Source checkers include new working files and omit deleted files before staging; release snapshots keep their separate identity contract.