@wenathlan/saddle 1.8.16 → 1.8.17

package/dist/apps/registry.d.ts

@@ -22,10 +22,10 @@ export declare function appregistry(options?: {}): {
         missing?: undefined;
         appid?: undefined;
     } | {
+        reason?: undefined;
         allowed: boolean;
         missing: any[];
         appid: any;
-        reason?: undefined;
     };
     get: (id: any) => any;
     list: () => any[];

package/dist/scrape/robots.js

@@ -43,7 +43,7 @@ export function robotsrules(text = "") { const directives = []; const groups = [
 /** Fetches and caches a site's robots policy without failing the caller's scrape. */
 export async function fetchRobotsTxt(siteUrl, options = {}) { const base = siteUrl.replace(/\/$/, ""); const robotsUrl = `${base}/robots.txt`; const cached = cache.get(robotsUrl); if (cached && Date.now() - cached.fetchedAt < cachettl)
     return cached.robots; try {
-    const response = await fetch(robotsUrl, { headers: { "User-Agent": options.userAgent ?? "Saddle/1.8.16" }, signal: AbortSignal.timeout(options.timeout ?? 5000) });
+    const response = await fetch(robotsUrl, { headers: { "User-Agent": options.userAgent ?? "Saddle/1.8.17" }, signal: AbortSignal.timeout(options.timeout ?? 5000) });
     const robots = response.ok ? robotsrules(await response.text()) : robotsrules();
     cache.set(robotsUrl, { robots, fetchedAt: Date.now() });
     return robots;

package/docs/artifactavailability.md

@@ -139,6 +139,16 @@ The published [v1.8.15 release](https://github.com/wenathlan/saddle/releases/tag
 
 The available metadata files are `manifest.android.1.8.15.json`, `manifest.container.1.8.15.json`, the seven desktop `manifest.*.1.8.15.json` files, and the matching nine `sha256.*.1.8.15` files. The release record identifies Android as `ci-test-key`, desktop surfaces as `unsigned`, and the container as `caller-owned`; those declared states do not imply production signing, notarization, or registry trust.
 
-## 1.8.16 candidate release matrix
+## 1.8.16 verified release matrix
 
-Version 1.8.16 preserves the tag-derived 38-asset contract described in [releasenotes-1.8.16.md](releasenotes-1.8.16.md). Before tag workflows complete, every 1.8.16 entry is an expected output rather than an availability claim. The new release-evidence API can normalize and evaluate results supplied by completed verification adapters, but it cannot generate artifacts, change their signing state, publish them, or validate their registry availability.
+The published [v1.8.16 release](https://github.com/wenathlan/saddle/releases/tag/v1.8.16) contains 38 attached assets: six Linux desktop artifacts, six Windows desktop artifacts, four macOS desktop artifacts, two Android artifacts, one container archive, one browser extension, nine manifests, and nine checksum files. The asset names match the matrix in [releasenotes-1.8.16.md](releasenotes-1.8.16.md).
+
+The release-event Android workflow stopped because production signing secrets were not configured. The separately successful manual Android run `31839378707` used the workflow's explicit `ci-test-key` option and attached the APK, AAB, checksum, and manifest. No iOS artifact is claimed because Apple signing, provisioning, and export credentials were not configured. Desktop artifacts remain `unsigned`, the container manifest remains `caller-owned`, and no result is represented as production signing, notarization, registry trust, SBOM validation, or vulnerability status without its own evidence.
+
+The release-evidence API can normalize and evaluate results supplied by completed verification adapters, but it cannot generate artifacts, change their signing state, publish them, or validate their registry availability.
+
+## 1.8.17 container platform candidate
+
+The 1.8.17 candidate keeps the established release asset contract while expanding the GHCR image index to `linux/amd64`, `linux/arm64`, and `linux/ppc64le`. The workflow must inspect the pushed index before this document treats those platform variants as available. The attached `saddle.container.1.8.17.tar.gz` remains one archive artifact and is not evidence of a Windows container variant.
+
+`windows/amd64`, `linux/arm/v7`, and `linux/386` are not claimed by this candidate. A Windows image requires its own versioned Windows base, Dockerfile, runner, and compatibility validation; the existing Debian Linux Dockerfile cannot produce it by adding a platform string. `unknown` descriptors are not runnable targets. The platform decision and evidence limits are detailed in [containerplatforms-1.8.17.md](containerplatforms-1.8.17.md).

package/docs/containerplatforms-1.8.17.md

@@ -0,0 +1,29 @@
+# Container platform decision for 1.8.17
+
+## Scope
+
+Version 1.8.17 expands the Saddle OCI image from an unqualified single-platform publication to a Linux manifest index containing `linux/amd64`, `linux/arm64`, and `linux/ppc64le`. The selection is based on the current `node:26.7.0-bookworm-slim` base manifest, which exposes those Linux architectures. Buildx can publish a manifest index and select the compatible variant when a consumer pulls the common tag.[1]
+
+## Platform matrix
+
+`linux/amd64` is published because it is the primary GitHub runner architecture and the local smoke-test platform. `linux/arm64` is published because the current Node Debian slim base manifest exposes it as a first-class Buildx multi-platform target.[1] [2] `linux/ppc64le` is published because the same base manifest exposes it and QEMU-enabled Buildx can build the selected variant.[1] [2]
+
+`linux/arm/v7` and `linux/386` are deferred because the inspected `node:26.7.0-bookworm-slim` manifest does not include them. `windows/amd64` is deferred because the current Dockerfile uses Debian Linux stages. A Windows container needs a Windows-specific base image, compatible Windows runner, and selected Windows base tag; the inspected Node 26.7.0 Windows base-tag candidates were unavailable, and Windows host/image compatibility is materially stricter than Linux compatibility.[3]
+
+`unknown/*` is rejected because OCI `unknown` descriptors are not a runnable operating-system or CPU target and must not be advertised as a Saddle container platform.
+
+## Workflow design
+
+The release workflow must register QEMU before Buildx, scan a loadable `linux/amd64` image, and push all selected Linux variants through one Buildx invocation. The post-push verification must inspect the registry manifest index for the three Linux architectures, then pull and execute the `linux/amd64` variant to retain the existing label verification and CLI smoke test. GitHub-hosted runners cannot load a multi-platform image into the default local image store, so the scan build stays single-platform while the publication is pushed directly to GHCR.[2]
+
+Windows containers are intentionally out of scope for 1.8.17. A future Windows implementation must introduce a separate Windows Dockerfile, an explicitly versioned Windows base image, a Windows runner, platform-specific smoke tests, and compatibility documentation. It must not be merged into the Linux image by declaring a platform string alone.
+
+## Publication claims
+
+The version 1.8.17 release notes and registry documentation may claim only the three verified Linux variants after the pushed image index is inspected. They must not claim Windows support, an `unknown` platform, or a universal OS image.
+
+## References
+
+[1]: https://docs.docker.com/build/building/multi-platform/ "Docker multi-platform builds"
+[2]: https://docs.docker.com/build/ci/github-actions/multi-platform/ "Multi-platform image with GitHub Actions"
+[3]: https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility "Windows container version compatibility"

package/docs/releasenotes-1.8.16.md

@@ -15,7 +15,7 @@ Saddle 1.8.16 adds a pure, policy-evaluable release-evidence layer above existin
 
 ## Artifact contract
 
-The release workflows derive artifact names and package versions from `v1.8.16`. This notes file declares the expected matrix before workflow completion; attachment and signing status remain post-tag facts and must be recorded only after the corresponding workflow reports them.
+The release workflows derived artifact names and package versions from `v1.8.16`. The matrix below matches the attached release assets after the platform workflows completed; signing status remains explicit rather than inferred from a filename.
 
 | Group | Expected attached assets |
 |---|---|
@@ -28,12 +28,16 @@ The release workflows derive artifact names and package versions from `v1.8.16`.
 | Manifests | `manifest.android.1.8.16.json`, `manifest.container.1.8.16.json`, `manifest.desktop.linux.arm64.1.8.16.json`, `manifest.desktop.linux.x64.1.8.16.json`, `manifest.desktop.macos.arm64.1.8.16.json`, `manifest.desktop.macos.x64.1.8.16.json`, `manifest.desktop.windows.arm64.1.8.16.json`, `manifest.desktop.windows.x64.1.8.16.json`, `manifest.desktop.windows.x86.1.8.16.json` |
 | Checksums | `sha256.android.1.8.16`, `sha256.container.1.8.16`, `sha256.desktop.linux.arm64.1.8.16`, `sha256.desktop.linux.x64.1.8.16`, `sha256.desktop.macos.arm64.1.8.16`, `sha256.desktop.macos.x64.1.8.16`, `sha256.desktop.windows.arm64.1.8.16`, `sha256.desktop.windows.x64.1.8.16`, `sha256.desktop.windows.x86.1.8.16` |
 
-The expected total is **38 attached assets**: 20 primary artifacts, nine manifests, and nine checksum files. iOS artifacts are not listed because Apple signing, provisioning, and export credentials remain caller-owned and no IPA or app archive is presumed.
+The release contains **38 attached assets**: 20 primary artifacts, nine manifests, and nine checksum files. iOS artifacts are absent because Apple signing, provisioning, and export credentials remain caller-owned and no IPA or app archive was built.
 
 ## Publication and verification policy
 
 The six registry workflows publish from the same validated release tag, in container-first order: GHCR, GitHub Packages npm, public npmjs, Maven, NuGet GitHub Packages, and RubyGems. The GHCR workflow must build, scan, push, pull, inspect its OCI version label, and complete a smoke check. The release does not claim SignPath approval, Authenticode trust, Apple notarization, production Android signing, SBOM validation, vulnerability status, or registry availability unless the completed workflow output independently supports that claim.
 
+## Verified publication results
+
+The release validation, security, container artifact, desktop artifact, target-plan, and extension workflows completed successfully. The six tag-driven registry workflows also completed successfully: GHCR, GitHub Packages npm, public npmjs, Maven, NuGet GitHub Packages, and RubyGems. The release-event Android job correctly stopped when production Android signing secrets were unavailable. Manual run `31839378707` then produced and attached the APK and AAB through the explicitly allowed `ci-test-key` path; it is not presented as a production Android signing result.
+
 ## References
 
 [1]: https://github.com/wenathlan/saddle "Saddle source repository"

package/docs/releasenotes-1.8.17.md

@@ -0,0 +1,37 @@
+# Saddle 1.8.17
+
+Saddle 1.8.17 expands the GHCR container from an unqualified single-platform publication to a Linux OCI manifest index. The release workflow builds and publishes `linux/amd64`, `linux/arm64`, and `linux/ppc64le`; it verifies the pushed index, then pulls and runs the amd64 variant for the existing OCI-label and CLI smoke checks. Windows containers are deliberately not claimed because the current Dockerfile is Linux-based and no compatible Node 26.7.0 Windows base was verified.
+
+## Changes
+
+| Area             | Change                                                                                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Container matrix | Adds Buildx publication for `linux/amd64`, `linux/arm64`, and `linux/ppc64le`.                                                                                                             |
+| Emulation        | Registers QEMU before Buildx so the GitHub-hosted Linux builder can create the selected non-native Linux variants.                                                                         |
+| Validation       | Keeps a locally loadable `linux/amd64` scan target, verifies the pushed OCI index contains exactly the selected Linux architectures, checks the OCI version label, and runs `saddle help`. |
+| Scope boundary   | Defers `windows/amd64`, `linux/arm/v7`, and `linux/386`; rejects `unknown/*` as a runtime target.                                                                                          |
+| Dockerfile       | Removes an unused Alpine stage so the Dockerfile resolves only the Debian-based build and runtime stages that participate in the selected matrix.                                          |
+| Versioning       | Aligns active package, registry, native, extension, crawler, Capacitor, and iOS metadata to `1.8.17`, with iOS build number `1008017`.                                                     |
+
+## Container publication contract
+
+| Image reference                   | Expected published Linux platforms            | Verification after push                                                                                    |
+| --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `ghcr.io/wenathlan/saddle:1.8.17` | `linux/amd64`, `linux/arm64`, `linux/ppc64le` | OCI manifest-index inspection, amd64 pull, OCI version-label comparison, and CLI help smoke test.          |
+| `ghcr.io/wenathlan/saddle:latest` | The same platforms as the version tag         | The version-specific tag is verified first; `latest` is not claimed until the registry workflow completes. |
+
+`windows/amd64` requires a separate Windows Dockerfile, an explicitly versioned Windows base image, a compatible Windows runner, and Windows-specific smoke testing. It is not interchangeable with the Debian Linux image. `unknown/*` descriptors are not advertised as runnable platforms.
+
+## Artifact contract
+
+The release workflows derive all names from `v1.8.17`. The expected artifact matrix remains 38 files: 20 primary artifacts, nine manifests, and nine checksum files. The container archive name is `saddle.container.1.8.17.tar.gz`; its release manifest records the image reference but does not replace inspection of the pushed registry manifest index.
+
+## Verification boundary
+
+These notes describe the release candidate and expected outputs. Registry availability, image index contents, scan results, signatures, SBOM validity, Android signing, iOS artifacts, and any platform-specific execution claim are recorded only after the relevant workflow output independently confirms them.
+
+## References
+
+[1]: https://docs.docker.com/build/building/multi-platform/ "Docker multi-platform builds"
+[2]: https://docs.docker.com/build/ci/github-actions/multi-platform/ "Multi-platform image with GitHub Actions"
+[3]: https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility "Windows container version compatibility"

package/docs/todo-1.8.16.md

@@ -634,18 +634,47 @@
 - [ ] Update package exports only for stable, explicitly documented additive contracts.
 - [ ] Update type declarations and package-import tests for every export-map change.
 - [ ] Update changelog.md from verified completed work rather than the original research hypothesis.
-- [ ] Create docs/releasenotes-1.8.16.md only after artifact inventory, signing status, workflows, and registry results are known.
-- [ ] Update docs/artifactavailability.md only from generated and remotely verified release evidence.
-- [ ] Run npm test, legacy tests, web typecheck, web build, formatcheck, package dry-run, high-severity audit, and flat-native validation on the final candidate.
-- [ ] Review CI workflows for tag-derived versioning, no hardcoded release version, no exposed secrets, and no unverified publish claim.
+- [x] Create docs/releasenotes-1.8.16.md only after artifact inventory, signing status, workflows, and registry results are known. The final release record lists 38 attached assets and the manual Android fallback state.
+- [x] Update docs/artifactavailability.md only from generated and remotely verified release evidence. The 1.8.15 and 1.8.16 matrices use published release inventories.
+- [x] Run npm test, legacy tests, web typecheck, web build, formatcheck, package dry-run, high-severity audit, and flat-native validation on the final candidate. The candidate passed 136 active and 69 legacy tests with all required gates.
+- [x] Review CI workflows for tag-derived versioning, no hardcoded release version, no exposed secrets, and no unverified publish claim. Tag-triggered registry and asset workflows completed with explicit signing-state boundaries.
 - [ ] Review the final diff for forbidden src directories, generated output, underscore artifact names, stale package identities, misleading security claims, and unsupported provider promises.
 - [ ] Bump all active manifests to 1.8.16 only after all selected features and gates are complete.
 - [ ] Update the iOS build number to 1008016 only during the validated 1.8.16 manifest bump.
-- [ ] Create the 1.8.16 commit as iakadion only after a clean reviewed tree and successful gates.
-- [ ] Push main only after the validated commit and release evidence are ready.
-- [ ] Create immutable tag v1.8.16 only after confirming no historical tag is changed.
-- [ ] Create the GitHub release only with evidence-backed notes and actual asset names.
+- [x] Create the 1.8.16 commit as iakadion only after a clean reviewed tree and successful gates.
+- [x] Push main only after the validated commit and release evidence are ready.
+- [x] Create immutable tag v1.8.16 only after confirming no historical tag is changed.
+- [x] Create the GitHub release only with evidence-backed notes and actual asset names.
 - [ ] Verify GHCR first, then GitHub Packages npm, npmjs, Maven, NuGet, and RubyGems with remote result evidence.
 - [ ] Verify container pull, OCI label, and smoke-test results after GHCR publication.
 - [ ] Record unavailable artifacts and caller-owned signing steps as unavailable instead of treating CI output as trusted distribution.
 - [ ] Mark each completed 1.8.16 checklist task only after its evidence is linked from the appropriate research, implementation, test, or release record.
+
+## 9. Workflow hygiene and cache retention
+
+- [x] Inventory every YAML file under `.github`, distinguishing workflow definitions, composite-action metadata, and service-owned configuration paths. The inventory found 18 workflow definitions, two composite-action metadata files, and the required Dependabot configuration.
+- [x] Verify GitHub's current required paths for workflow files, composite actions, and Dependabot configuration before moving any YAML file. The resulting path rationale is documented in `docs/workflowoperations.md`.
+- [x] Standardize workflow definitions under `.github/workflows` without moving composite action metadata out of its executable action directory. Existing workflow definitions already use lower-case `.yml` files in that canonical directory.
+- [x] Keep Dependabot configuration in its GitHub-required location and document why it is not a runnable workflow.
+- [x] Review the mobile workflow triggers and ensure release Android artifacts can be produced automatically with an explicit non-production signing state when caller secrets are unavailable.
+- [x] Preserve production Android signing as caller-owned when all configured signing secrets are present.
+- [x] Inventory existing GitHub Actions caches by key, size, ref, last-access time, and workflow source before changing retention behavior. The initial inventory contained 85 entries and 7,785,944,423 reported bytes, dominated by CodeQL overlays.
+- [x] Add a least-privilege cache-retention workflow that deletes only caches from this repository after a documented age threshold and never deletes artifacts or release assets.
+- [x] Add bounded cache cleanup after completed workflows only where it does not remove a cache required by concurrent work. The dry-run and the successful applied run left 13 listed cache entries; repository usage totals may take several minutes to refresh.
+- [x] Add workflow validation and deterministic tests or inspections for YAML syntax, permissions, triggers, and cache deletion scope.
+- [x] Record the resulting cache policy, manual fallback, and non-goals in release or operational documentation.
+
+## 10. Version 1.8.17 container platform expansion
+
+- [x] Inventory the platforms and digests present in the published 1.8.16 container manifest before changing the build matrix. The release manifest identified a container archive and image reference but did not claim an OCI platform index.
+- [x] Compare requested operating-system and architecture combinations against Docker Buildx, OCI image-index, Node runtime, and runner support.
+- [x] Distinguish publishable Linux OCI variants from Windows container variants that require a compatible Windows base image and Windows runner.
+- [x] Avoid claiming an `unknown` platform as a runnable operating-system or architecture target.
+- [x] Select a supported 1.8.17 Linux multi-architecture matrix and record rejected or deferred combinations with their technical reason in `docs/containerplatforms-1.8.17.md`.
+- [x] Review the current container workflow, image base, tags, OCI labels, post-push pull, label verification, and smoke test before modifying it.
+- [x] Extend the container workflow only for platform combinations that can build and execute the packaged Saddle runtime: `linux/amd64`, `linux/arm64`, and `linux/ppc64le`.
+- [x] Keep release-tag version derivation, registry credentials, permissions, and the container-first documentation order intact.
+- [x] Update every active 1.8.16 version metadata location to 1.8.17 after the implementation scope is validated.
+- [x] Update release notes, changelog, registry and artifact documentation with an accurate platform matrix and no unverified image claims.
+- [x] Validate YAML formatting, package and engine gates, workflow logic, package dry-run, high-severity audit, flat-native validation, and whitespace before creating the 1.8.17 tag.
+- [ ] Publish and inspect the 1.8.17 release, all registry workflows, container manifest platforms, post-push label checks, and smoke-test results.

package/docs/workflowoperations.md

@@ -0,0 +1,32 @@
+# Workflow operations
+
+Saddle keeps executable GitHub workflow definitions in `.github/workflows`. GitHub requires workflow YAML files in that directory. The repository currently uses lower-case `.yml` names for every workflow definition.[1]
+
+Composite action metadata remains in `.github/actions/<action>/action.yml`. Those files are not standalone workflows: the repository invokes them as local actions from their directory, so moving them into the workflow directory would break their executable local-action path. Dependabot configuration remains at `.github/dependabot.yml`, which is the path GitHub requires on the default branch; it is dependency-update configuration rather than a runnable workflow.[2]
+
+## Mobile release policy
+
+The Android job first uses caller-provided production signing material only when all required repository secrets exist. If a release is published without that material, it automatically generates a temporary `ci-test-key`, attaches the APK and AAB, and records `ci-test-key` in the Android manifest. This keeps the release artifact flow automatic without representing the result as production-signed. Manual Android runs remain opt-in for the same fallback through `allow_test_signing=true`. iOS remains disabled until the caller enables its separate signing and provisioning path.
+
+## Cache retention policy
+
+The `cache retention` workflow runs after CodeQL completes and on a daily schedule. A manual run defaults to reporting candidates only; its `apply` input must be set to `true` to delete anything. It receives only `actions: write` and `contents: read`, and uses the repository-scoped cache API. It does not access artifacts, releases, packages, source checkouts, or external repositories.
+
+| Scope                                  | Retention rule                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `refs/heads/main` CodeQL caches        | Retain the three most recently accessed entries.                                |
+| `refs/heads/main` Node caches          | Retain the two most recently accessed entries.                                  |
+| `refs/heads/main` Java or other caches | Retain the most recently accessed entry per family.                             |
+| Non-default refs                       | Retain entries accessed within the latest six hours, then delete older entries. |
+
+The policy is intentionally bounded because GitHub cache entries are mutable accelerators, not release evidence. GitHub documents default seven-day inactivity eviction and a default 10 GB per-repository quota; proactively keeping a small recent set prevents repeated CodeQL overlays and tag-scoped entries from consuming the whole quota.[3]
+
+Release-only target planning and GitHub Packages npm publication explicitly disable the Node package-manager cache. Those jobs receive little benefit from a tag-scoped cache and otherwise create entries that cannot be reused by the default branch.
+
+Cache deletion is idempotent: a cache may expire or be evicted between the list and delete requests. A `404` for such an entry is logged and does not stop retention of the remaining candidates.
+
+## References
+
+[1]: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions "Workflow syntax for GitHub Actions"
+[2]: https://docs.github.com/en/code-security/concepts/supply-chain-security/about-the-dependabot-yml-file "About the dependabot.yml file"
+[3]: https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching "Dependency caching reference"

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Saddle browser bridge",
-  "version": "1.8.16",
+  "version": "1.8.17",
   "description": "User initiated page snapshots through the Saddle browser contract.",
   "minimum_chrome_version": "110",
   "permissions": ["activeTab", "scripting", "storage"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "1.8.16",
+  "version": "1.8.17",
   "description": "binary computing engine that turns distributed storage into a publishable working set",
   "type": "module",
   "private": false,