feat: --build-timestamp + dev.ocx.sh continuous deploy

Add `--build-timestamp [datetime|date|none]` to `ocx package push` to
attach UTC build metadata to published tags. Bare flag defaults to
`datetime`; identifiers already carrying build metadata or lacking the
`X.Y.Z` core are rejected (`#[non_exhaustive] Error::BuildMeta`,
`require_equals=true`). Cascade behaviour unchanged — `Version::parent()`
strips build before deriving rolling targets. Shared
`BuildTimestampFormat` enum + `build_timestamp` helper move from
`ocx_mirror` into `ocx_lib::package::version::build_meta`; mirror
callers pass `None` because their version strings are pre-formatted via
`normalize_version`. `Version::with_build` attaches build metadata via
the typed model instead of string formatting.

Add `deploy-dev.yml` triggered by every `main` push and manual
`workflow_dispatch`. Always builds linux x86_64 and aarch64 (gnu+musl)
for `ocx` and `ocx-mirror` via cargo-zigbuild, publishes to
`dev.ocx.sh/ocx:<core>-dev_<TS>` and
`dev.ocx.sh/ocx:mirror-<core>-dev_<TS>`. Dispatch input
`include_cross_platform: true` extends matrix to darwin + windows
(amd64/arm64). Version core from `git-cliff --bumped-version`; empty
output fails loudly. Extract `oci-publish.yml` as reusable workflow
handling `bare` (dev) and `cargo-dist` (prod) artifact sources;
`post-release-oci-publish.yml` delegates platform-loop + push.
`.github/actions/build-rust` gains `use_zigbuild: bool` so dev can
cross-compile aarch64+musl from x86 ubuntu without leaving the native
path. Dev publish job uses `dev.ocx.sh` GitHub Environment for secret
gating (`REGISTRY_USER`/`REGISTRY_TOKEN` mapped to
`OCX_AUTH_dev_ocx_sh_USER`/`_TOKEN`).

CI security hardening from swarm-review: pin `messense/cargo-xwin` by
digest (CWE-829), regex-validate `inputs.registry` (CWE-78),
`persist-credentials: false` on checkouts (CWE-522), explicit `secrets`
blocks replacing `secrets: inherit`, registry allowlist defense-in-depth,
`shell: bash` on windows run steps, drop `|| true` masking git-cliff
failures, hard-fail on missing artifacts, prerelease guard on publish
job. Build timestamp baked into `version_tag` caller-side; the
`apply_build_timestamp` input is removed for single source-of-truth
across the matrix push loop.

Tests: `Version::with_build` invariants (bare patch / variant pre-release
/ already present / no patch), publisher `apply_build_meta`,
`BuildTimestampFormat` round-trip, and
`test/tests/test_package_push_build_timestamp.py` covering CLI surface
(datetime / date / none / bare / cascade / double-push / NoPatch).

Docs: CHANGELOG `[Unreleased]` entries, ADR
`adr_version_build_separator.md` → Accepted, `subsystem-package.md`
adds `version/build_meta.rs` row, `subsystem-mirror.md` re-export note,
dead ADR link → prose, `command-line.md` documents absent-flag clause.

Author: michael-herwig

.claude/artifacts/adr_version_build_separator.md

@@ -2,8 +2,9 @@
 
 ## Metadata
 
-**Status:** Proposed
+**Status:** Accepted
 **Date:** 2026-03-12
+**Date Accepted:** 2026-05-14
 **Deciders:** mherwig
 **Beads Issue:** N/A
 **Related PRD:** N/A

.claude/rules/subsystem-cli-commands.md

@@ -69,7 +69,7 @@ ADR: [`adr_cli_high_low_layering.md`](../../.claude/artifacts/adr_cli_high_low_l
 | `lock` | Resolve project tool tags to digests and write `ocx.lock` | No | `-g/--group` |
 | `package pull PKGS...` | Download to object store only | N/A (is pull) | `-p` |
 | `package create PATH` | Bundle directory into archive | No | `-o`, `-m`, `-l`, `-j`, `--force` |
-| `package push -i ID LAYERS...` | Publish archive to registry | No | `-i/--identifier` (required), `-c/--cascade`, `-n`, `-m`, `-p` |
+| `package push -i ID LAYERS...` | Publish archive to registry | No | `-i/--identifier` (required), `-c/--cascade`, `-n`, `-m`, `-p`, `--build-timestamp [datetime\|date\|none]` |
 | `package describe ID` | Push description metadata | No | `--readme`, `--logo`, `--title` |
 | `package test -i ID LAYERS... -- CMD` | Materialize + exec locally (no registry) | **Yes** (deps only) | `-i/--identifier` (required), `-p`, `-m`, `--keep`, `-o/--output`, `--self`, `--clean` |
 | `package info ID` | Display description metadata | No | `--save-readme`, `--save-logo` |

.claude/rules/subsystem-mirror.md

@@ -20,7 +20,7 @@ Separate crate: mirror tool standalone binary, own CLI, not part of `ocx` packag
 | `command/check.rs` | Dry-run sync |
 | `command/validate.rs` | Spec validation only |
 | `command/options.rs` | Shared `SyncOptions` (--exact-version, --latest, --fail-fast) |
-| `spec/spec.rs` | `MirrorSpec` root, `load_spec()`, extends chain resolution |
+| `spec/spec.rs` | `MirrorSpec` root, `load_spec()`, extends chain resolution; `build_timestamp` field uses `BuildTimestampFormat` re-exported from `ocx_lib::package::version` |
 | `spec/source.rs` | `Source` enum (GithubRelease, UrlIndex) |
 | `spec/target.rs` | `Target` (registry + repository) |
 | `spec/assets.rs` | `AssetPatterns` (platform → regex[] mapping) |
@@ -40,7 +40,7 @@ Separate crate: mirror tool standalone binary, own CLI, not part of `ocx` packag
 | `pipeline/mirror_result.rs` | `MirrorResult`: Pushed/Skipped/Failed |
 | `resolver.rs` | `resolve_assets()`: apply regex patterns to asset names |
 | `filter.rs` | `filter_versions()`: apply bounds, prerelease skip, backfill cap |
-| `normalizer.rs` | `normalize_version()`: add build timestamp |
+| `normalizer.rs` | `normalize_version()`: attach build timestamp to a version string; re-exports `build_timestamp` from `ocx_lib::package::version` (defined in `version/build_meta.rs`) |
 | `error.rs` | `MirrorError`: SpecInvalid, SpecNotFound, ExecutionFailed, SourceError |
 
 ## Pipeline Architecture

.claude/rules/subsystem-package.md

@@ -35,7 +35,8 @@ Tagged enum metadata (`Metadata::Bundle`) supports future format versions, no br
 | `bundle.rs` | `BundleBuilder`: tar archive creation with configurable compression |
 | `cascade.rs` | Cascade algebra: `decompose()`, `cascade()`, `resolve_cascade_tags()`, `push_with_cascade()` |
 | `tag.rs` | `Tag` enum: Latest, Internal(InternalTag), Version, Canonical, Other |
-| `version.rs` | `Version` struct: semver-inspired with build + prerelease, rolling tag support |
+| `version.rs` | `Version` struct: semver-inspired with build + prerelease, rolling tag support; `with_build(seg)` attaches a build-metadata segment (errors if no `X.Y.Z` core or build already present); re-exports `BuildTimestampFormat` + `build_timestamp` from `version/build_meta.rs` |
+| `version/build_meta.rs` | `BuildTimestampFormat` enum (`Datetime` / `Date` / `None`); `build_timestamp(format)` returns the UTC stamp string or `None`; `BuildMetaError` enum (`NoPatch` / `AlreadyPresent`) |
 | `install_info.rs` | `InstallInfo`: identifier + metadata + content path |
 | `description.rs` | Package description metadata (title, description, keywords, README, logo) |
 

.github/actions/build-rust/action.yml

@@ -1,10 +1,14 @@
 name: Build Rust Binary
-description: Build an ocx binary for a given target (native builds only)
+description: Build an ocx binary for a given target (native builds or zig cross-compile)
 
 inputs:
   target:
     description: Rust target triple
     required: true
+  use_zigbuild:
+    description: Use cargo-zigbuild instead of cargo build (required for cross-compiling aarch64-linux and musl from x86 runners)
+    required: false
+    default: "false"
 
 runs:
   using: composite
@@ -14,15 +18,38 @@ runs:
       with:
         toolchain: stable
         targets: ${{ inputs.target }}
+    - name: Install target on rust-toolchain.toml channel
+      # rust-toolchain.toml pins an explicit channel; dtolnay's `targets:` only
+      # adds the target to the `stable` alias toolchain. Re-add against the
+      # pinned channel resolved from the workspace root so cargo finds std/core.
+      shell: bash
+      env:
+        TARGET: ${{ inputs.target }}
+      run: rustup target add "$TARGET"
     - name: Rust Cache
       uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
       with:
         save-if: ${{ github.ref == 'refs/heads/main' }}
-    - name: Build
+    - name: Install Zig
+      if: ${{ inputs.use_zigbuild == 'true' }}
+      uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1
+    - name: Install cargo-zigbuild
+      if: ${{ inputs.use_zigbuild == 'true' }}
+      uses: taiki-e/install-action@58e862542551f667fa44c8a2a4a1d64ad477c96a # v2.75.17
+      with:
+        tool: cargo-zigbuild
+    - name: Build (cargo)
+      if: ${{ inputs.use_zigbuild != 'true' }}
       shell: bash
       env:
         TARGET: ${{ inputs.target }}
       run: cargo build --release --target="$TARGET" --locked
+    - name: Build (zigbuild)
+      if: ${{ inputs.use_zigbuild == 'true' }}
+      shell: bash
+      env:
+        TARGET: ${{ inputs.target }}
+      run: cargo zigbuild --release --target="$TARGET" --locked
     - name: Prepare Binaries
       shell: bash
       env:

.github/workflows/deploy-dev.yml

@@ -0,0 +1,164 @@
+name: Deploy Dev
+
+# Manual deploy pipeline. Run via `gh workflow run "Deploy Dev"` or the Actions
+# UI. Builds all production targets (linux musl + darwin + windows) for `ocx`
+# and `ocx-mirror`, then publishes them to `dev.ocx.sh/ocx:<core>-dev_<TS>`
+# (and `mirror-<core>-dev_<TS>`).
+#
+# Musl-only linux matches the prod target set in `post-release-oci-publish.yml`.
+# Cross-compile uses cargo-zigbuild on ubuntu-22.04 (linux), native build on
+# macos-latest (darwin), and `cargo xwin` in a container on ubuntu-latest
+# (windows). Published artifacts are tagged as pre-release (`-dev_<TS>`) so
+# they cannot collide with the stable release graph.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Serialize runs so the timestamp suffix stays monotonic; never cancel a
+# publish in flight.
+concurrency:
+  group: deploy-dev-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  compute-version:
+    name: Compute version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.cliff.outputs.version }}
+      version_tag: ${{ steps.cliff.outputs.version_tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install git-cliff
+        uses: taiki-e/install-action@58e862542551f667fa44c8a2a4a1d64ad477c96a # v2.75.17
+        with:
+          tool: git-cliff
+      - name: Compute next version and timestamp
+        id: cliff
+        shell: bash
+        run: |
+          set -euo pipefail
+          raw="$(git-cliff --bumped-version)"
+          version="${raw#v}"
+          if [[ -z "$version" ]]; then
+            echo "::error::git-cliff --bumped-version returned empty output; no commits since last tag — refusing to publish a dev build"
+            exit 1
+          fi
+          ts="$(date -u +%Y%m%d%H%M%S)"
+          echo "version=${version}"                         | tee -a "$GITHUB_OUTPUT"
+          echo "version_tag=${version}-dev_${ts}"           | tee -a "$GITHUB_OUTPUT"
+
+  build-linux:
+    name: Build (${{ matrix.target }})
+    needs: [compute-version]
+    # ubuntu-22.04 matches the runner cargo-dist plans for linux targets —
+    # older glibc baseline for portability of any future gnu targets.
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-unknown-linux-musl
+          - aarch64-unknown-linux-musl
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: true
+          persist-credentials: false
+      - name: Build
+        uses: ./.github/actions/build-rust
+        with:
+          target: ${{ matrix.target }}
+          # cargo-zigbuild covers aarch64 and musl targets uniformly from
+          # x86_64 ubuntu runners; matches what cargo-dist uses for prod.
+          use_zigbuild: true
+
+  build-darwin:
+    name: Build (${{ matrix.target }})
+    needs: [compute-version]
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-apple-darwin
+          - aarch64-apple-darwin
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: true
+          persist-credentials: false
+      - name: Build
+        uses: ./.github/actions/build-rust
+        with:
+          target: ${{ matrix.target }}
+
+  build-windows:
+    name: Build (${{ matrix.target }})
+    needs: [compute-version]
+    runs-on: ubuntu-latest
+    container:
+      # messense/cargo-xwin has no stable versioned tag — pinned by digest. Re-pin with:
+      #   docker pull messense/cargo-xwin && docker inspect --format='{{index .RepoDigests 0}}' messense/cargo-xwin
+      image: messense/cargo-xwin@sha256:543cdaeb5cd3ed0ca1dd29b9e5aba4100aa0008f8ed088b793f3b9255a635869
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-pc-windows-msvc
+          - aarch64-pc-windows-msvc
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: true
+          persist-credentials: false
+      - name: Install Rust target
+        shell: bash
+        run: rustup target add ${{ matrix.target }}
+      - name: Build
+        shell: bash
+        run: cargo xwin build --release --target=${{ matrix.target }} --locked
+      - name: Prepare Binaries
+        shell: bash
+        run: |
+          cp target/${{ matrix.target }}/release/ocx.exe ocx-${{ matrix.target }}.exe
+          cp target/${{ matrix.target }}/release/ocx-mirror.exe ocx-mirror-${{ matrix.target }}.exe
+      - name: Upload ocx Binary
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ocx-${{ matrix.target }}
+          path: ocx-${{ matrix.target }}.exe
+          compression-level: 0
+          retention-days: 1
+      - name: Upload ocx-mirror Binary
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ocx-mirror-${{ matrix.target }}
+          path: ocx-mirror-${{ matrix.target }}.exe
+          compression-level: 0
+          retention-days: 1
+
+  publish:
+    name: Publish to dev.ocx.sh
+    needs: [compute-version, build-linux, build-darwin, build-windows]
+    uses: ./.github/workflows/oci-publish.yml
+    with:
+      registry: dev.ocx.sh
+      repo: ocx
+      version_tag: ${{ needs.compute-version.outputs.version_tag }}
+      variants: '["","mirror"]'
+      targets: '["x86_64-unknown-linux-musl","aarch64-unknown-linux-musl","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc","aarch64-pc-windows-msvc"]'
+      environment: dev.ocx.sh
+    secrets:
+      REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

.github/workflows/notify-discord.yml

@@ -8,7 +8,7 @@ on:
     types: [published]
 
   workflow_run:
-    workflows: ["Basic Verification", "License Compliance", "Deploy Canary", "Deploy Website"]
+    workflows: ["Basic Verification", "License Compliance", "Deploy Canary", "Deploy Website", "Deploy Dev"]
     types: [completed]
 
   deployment_status: