release(0.3.2): repair the publish path end to end and lead the README with the product

[oscharko]

Summary

0.3.1 reached its GitHub release and npm under next, but its latest promotion was blocked by a defect in the publish verification itself — and the gates correctly bind every publish to the exact tagged code, so the repair ships as 0.3.2 with the identical product. This PR carries three things:

1. The publish path, repaired end to end (every 0.3.1 outage, fixed at the owning layer)

• Digest verification restricts its collision refusal to the four published download names; per-target evidence files sharing a name across staging artifacts (SHA256SUMS.txt, sbom.cdx.json, …) no longer refuse a healthy release.
• Evaluation artifacts are fetched by their immutable ids through a binary-safe port (in-process fail-closed ZIP32 reader added to zip-archive.mjs); a rerun of the build run can neither substitute bytes nor block a verified release. The mutable run listing is no longer consulted — pinned by a test that throws on any listing call.
• --provenance is passed exactly where an OIDC provider exists; token publishes carry no attestation instead of dying on the flag.
• The publish states strict-ssl=true in its own npmrc and environment; a user-level strict-ssl=false neither weakens nor blocks a release.
• The release-owner allowlist resolves through one shared helper (scripts/lib/release-owner-allowlist.mjs) in both the producer and the publisher.
• release.yml pins the governed npm from EXPECTED_PACKAGE_MANAGER, held in lockstep by release-workflow-npm-pin.test.mjs — the drifted hand pin (11.18.0 vs 11.16.0) killed the CI publish from the frozen 0.3.1 tag.
• The release-branch lookup treats only an explicit (HTTP 404) as absent and travels URL-encoded; --public-release requires an entirely successful build run; an auth preflight refuses a live publish with neither token nor OIDC before prepack.

2. The README, led by the product — one page: what Keiko is, the desktop downloads with first-launch steps, a two-command npm quickstart, what the 0.3 line ships, the principles. Developer content lives in CONTRIBUTING.md and docs/.

3. The 0.3.2 release cut — versions across all workspaces and constants, lockfile, and the reviewed release-impact entry with the owner approval (github-issue-comment:oscharko-dev/Keiko#2802#5235616947, verified live).

Reuse / No-Duplication

The ZIP reader extends the existing zip-archive.mjs (same constants, same traversal rule, round-trip-tested against its writer). Allowlist resolution is ONE shared helper consumed by both release scripts. No new subsystem.

Verification

Run locally on this branch:

• All touched suites green: release-publish-pipeline 71, portable-release-verification 76, release-portable-prerelease 69, portable-evaluation-manifest 18, zip-archive 14, release-workflow-npm-pin 1, zizmor-anchors 12 — 318 total in the battery run
• npm run typecheck PASS, npm run lint clean, npm run format:check clean
• npm run check:version-consistency PASS (0.3.2 everywhere), npm run check:release-impact PASS and the publish-mode check PASS with the approval verified live
• npm run gates:sonar PASS

Update-Impact

Release metadata and release tooling; no product runtime change relative to 0.3.1. Recorded in the catalog (2026-08-10-keiko-0.3.2-public-download): no state action required.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[coderabbitai]

Warning

Review limit reached

@oscharko, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ed7bbfe6-9e47-4cdf-bd8c-5659dae742e0

📥 Commits

Reviewing files that changed from the base of the PR and between 78fb97b and 72ea8ea.

📒 Files selected for processing (10)

• docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md
• release-impact.catalog.json
• scripts/__tests__/check-zizmor-anchors.test.mjs
• scripts/__tests__/portable-evaluation-manifest.test.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/zip-archive.test.mjs
• scripts/check-zizmor-anchors.mjs
• scripts/lib/portable-evaluation-manifest.mjs
• scripts/lib/zip-archive.mjs
• scripts/release-publish.mjs

📝 Walkthrough

Walkthrough

Changes

The release pipeline now validates immutable ZIP artifacts, applies signing-scope gates, strengthens evaluation and stable publication checks, and supports conditional npm provenance. Repository packages, exported version constants, tests, documentation, and release metadata are aligned with version 0.3.2.

Release pipeline

Layer / File(s)	Summary
Release scope and contracts .github/workflows/portable-assets.yml, release-impact.catalog.json, docs/adr/*, README.md	Release metadata and workflow gates now distinguish evaluation and production signing scopes. The README and release contracts describe the 0.3 release.
ZIP and artifact verification scripts/lib/zip-archive.mjs, scripts/lib/portable-release-verification.mjs, scripts/__tests__/*	Artifact verification uses immutable records and ZIP extraction with path, size, CRC, and digest validation.
Evaluation release safeguards scripts/release-portable-prerelease.mjs, scripts/lib/release-owner-allowlist.mjs	Public releases require successful, attempt-consistent workflow evidence and encoded branch lookups.
Stable publication orchestration scripts/release-publish.mjs, scripts/__tests__/release-publish-pipeline.test.mjs	Stable publication verifies portable assets, enforces TLS, validates authentication, and requests provenance only with OIDC credentials.
Governed npm pin .github/workflows/release.yml, scripts/check-runtime-toolchain.mjs, scripts/__tests__/release-workflow-npm-pin.test.mjs	The release workflow and regression test use the exported npm@11.16.0 toolchain constant.

Package version alignment

Layer / File(s)	Summary
Package manifests and exported versions package.json, packages/*/package.json, packages/*/src/version.ts, packages/keiko-contracts/src/index.ts	Package versions, internal dependency pins, and exported version constants are updated from 0.3.0 to 0.3.2.
Manifest-backed version assertions packages/*/src/*.test.ts	Version tests read package.json and compare exported constants with the packaged manifest version.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• oscharko-dev/Keiko#3054: Both changes update package manifests and exported version constants for successive releases.
• oscharko-dev/Keiko#3051: Both changes update stable-release portable-asset gating for evaluation-scoped artifacts.
• oscharko-dev/Keiko#3037: Both changes harden scripts/release-portable-prerelease.mjs and its tests.

Suggested labels: 🕐 40+ Minutes, dependencies, javascript

🚥 Pre-merge checks | ✅ 1 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers summary, reuse, verification, and release impact, but omits Scope, Delivery Board, Product Impact, Review And Closure, Risk Notes, and an issue reference.	Add the missing template sections, issue reference, required checkbox states, risk notes, and closure evidence.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses an imperative conventional subject and names the repaired publish path and product-focused README outcome.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[keiko-for-quality]

Keiko for Quality — run summary

· head 72ea8ea · 2026-08-10T05:33:36Z · engine v1.8.4 · action 0c53cb11a924ba62dc2172316dee4ecf4a758360

Metric	Count
Total paths	79
Reviewable	77
Excluded	2
Mechanically clean	0
Critical pointer changes (content not reviewable)	0
Replayed from cache	75
Cache miss (path-set shape changed)	0
Freshly reviewed	2
Findings published	1
Suppressed (intra-run duplicate)	0
Suppressed (exact duplicate)	0
Suppressed (similar)	0
Suppressed (dispositioned)	4
Suppressed (outdated recurrence)	0
Rejected (sanitization)	0
Rejected (placement)	0
Read-back failures	0
API failures	0
Duration (s)	33
Tokens per published finding	53220

Budget: 550030 tokens allotted, 53220 reported

Recent runs

• 72ea8ea · complete · fresh 2 · replayed 75 · 33s
• 2e9feb2 · complete · fresh 11 · replayed 66 · 63s
• 15208c2 · complete · fresh 20 · replayed 57 · 84s
• 78fb97b · complete · fresh 2 · replayed 71 · 10s
• c022234 · complete · fresh 4 · replayed 68 · 26s

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 48b421d41b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 10

♻️ Duplicate comments (1)

scripts/release-portable-prerelease.mjs (1)

1219-1239: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Build the evaluation manifest before mutating the release.

evaluationManifestFor() can fail when artifact identities are invalid. It currently runs after ensureTagRefAtBuiltCommit() creates the tag and after deleteInterruptedDraft() deletes a resumable draft. A failed manifest leaves repository state that requires manual recovery.

Resolve the manifest after the plan-only return and before Lines 1219-1220. Then pass the saved path to createRelease().

Proposed fix

   if (options.planOnly) {
     reportPlan(body, tag, hasPendingDraft);
     return;
   }
+  const evaluationManifestPath = evaluationManifestFor({
+    options,
+    workDir,
+    tag,
+    repository,
+    runId,
+    attempt: view.attempt,
+    digests,
+    sourceCommitSha: view.headSha,
+  });
   ensureTagRefAtBuiltCommit(tag, view.headSha);
   if (hasPendingDraft) deleteInterruptedDraft(tag);
   createRelease({
@@
-    evaluationManifestPath: evaluationManifestFor({
-      options,
-      workDir,
-      tag,
-      repository,
-      runId,
-      attempt: view.attempt,
-      digests,
-      sourceCommitSha: view.headSha,
-    }),
+    evaluationManifestPath,
   });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/release-portable-prerelease.mjs` around lines 1219 - 1239, Move the
evaluationManifestFor call out of the createRelease arguments and execute it
after the plan-only return but before ensureTagRefAtBuiltCommit and
deleteInterruptedDraft. Store its resulting path, then pass that saved path to
createRelease via evaluationManifestPath so manifest failures occur before
release state is mutated.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/zizmor.yml:
- Around line 93-95: Update .github/zizmor.yml lines 93-95 so
portable-assets.yml:166 and portable-assets.yml:236 target the MSVC steps
invoking vswhere.exe and vcvars64.bat, not the 7z verification step. Update
.github/zizmor.yml lines 96-101 so release.yml:145 targets the npm@11.16.0
installation step. Extend npm run check:zizmor-anchors to validate both
portable-assets anchors and the release.yml anchor against their intended
commands and version pin.

In `@docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md`:
- Around line 66-76: Update ADR-0130’s D2 and Consequences sections to replace
all stale npm@10.9.8 and 10.9.x references with the governed npm@11.16.0 pin,
and remove wording that describes the publish npm as newer than the repository
npm. Add a Version History entry documenting this pin update, following the
ADR’s existing Revision Policy and table format.

In `@release-impact.catalog.json`:
- Line 1028: Update the userVisibleSummary text to describe the four published
artifacts as “four published downloads” instead of “four published archives,”
preserving the surrounding release description unchanged.

In `@scripts/__tests__/portable-release-verification.test.mjs`:
- Around line 517-521: Update the mock’s collectRunArtifactDigests function to
accept the production four-argument signature, including relevantAssetNames, and
record that fourth argument under the names key while preserving artifacts
separately. Update the related assertions to verify the forwarded relevant asset
names, ensuring the test exercises portableReleaseGate’s filtering contract.

In `@scripts/__tests__/registry-install-smoke-security.test.mjs`:
- Around line 110-113: Replace the substring assertions in the provenance test
with a reference to the established behavioral coverage in
release-publish-pipeline.test.mjs, which verifies both conditional branches.
Remove the direct --provenance and ACTIONS_ID_TOKEN_REQUEST_TOKEN source checks
while preserving coverage through those existing tests.

In `@scripts/__tests__/zip-archive.test.mjs`:
- Around line 332-357: Extend the extractZipArchiveEntries tests with two
malformed-archive cases using the existing reader fixtures: mutate a byte in the
compressed stream and assert the declared size or checksum error, then truncate
the archive immediately after its local header and assert the truncated error.
Keep the tests focused on the extractor’s extractEntryData and readAt refusal
paths, alongside the existing healthy and hostile-entry cases.

In `@scripts/lib/portable-release-verification.mjs`:
- Around line 520-527: Validate manifest-declared artifact fields inside the
exported collection flow before use: require each declared name to be a safe
artifact name that cannot escape root via join, and require each declared id to
be numeric before constructing the GitHub API request in fetchArtifactZip or its
caller. Reject invalid declarations by returning the existing empty Map failure
result, rather than relying on runArtifactDigestFailures’ caller-side
validation.

In `@scripts/lib/zip-archive.mjs`:
- Around line 344-348: Update inflatedEntryData to pass the declared entry.size
as maxOutputLength when calling inflateRawSync, ensuring decompression is
bounded before centralEntryData and extractEntryData compare the resulting
length. Preserve the existing handling for STORE_METHOD and unsupported
compression methods.
- Around line 419-428: Update both readZipArchiveEntries() and
extractZipArchiveEntries() to reject ZIP64 EOCD sentinel values before using the
parsed fields: refuse a count of 0xffff or a directory offset of 0xffffffff with
the established malformed/unsupported ZIP error behavior. Apply the validation
immediately after locating the EOCD and before iterating entries or reading the
central directory.

In `@scripts/release-publish.mjs`:
- Around line 250-265: Update fetchRunArtifactZip to enforce ADR-0121’s transfer
deadline and maximum ZIP size while fetching the artifact, rather than relying
on unbounded spawnSync output. Treat timeout, oversize, and other refusal
conditions as failures, remove the partial destination file before returning,
and preserve cleanup of the file descriptor; add negative tests covering timeout
and size-limit failures.

---

Duplicate comments:
In `@scripts/release-portable-prerelease.mjs`:
- Around line 1219-1239: Move the evaluationManifestFor call out of the
createRelease arguments and execute it after the plan-only return but before
ensureTagRefAtBuiltCommit and deleteInterruptedDraft. Store its resulting path,
then pass that saved path to createRelease via evaluationManifestPath so
manifest failures occur before release state is mutated.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0bf37ac2-fece-46a3-8c63-f57917bc6fb0

📥 Commits

Reviewing files that changed from the base of the PR and between 8786a0d and 78fb97b.

📒 Files selected for processing (30)

• .github/workflows/portable-assets.yml
• .github/zizmor.yml
• docs/adr/ADR-0121-portable-managed-install-and-release-asset-update-authority.md
• docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md
• docs/local-runtime-state-contract.md
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-workspace/src/index.test.ts
• release-impact.catalog.json
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/portable-runtime.test.mjs
• scripts/__tests__/registry-install-smoke-security.test.mjs
• scripts/__tests__/release-portable-prerelease.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs
• scripts/__tests__/zip-archive.test.mjs
• scripts/lib/portable-release-verification.mjs
• scripts/lib/zip-archive.mjs
• scripts/release-portable-prerelease.mjs
• scripts/release-publish.mjs

📜 Review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (14)

**/*.{ts,tsx,mjs,js,json,md,yml,yaml}

📄 CodeRabbit inference engine (AGENTS.md)

Prefer working, clean, secure, verified code over contradictory ADR text; when repairing behavior, update affected ADR sections in the same change and do not create a replacement ADR solely to repair outdated text.

Files:

• docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md
• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• scripts/__tests__/portable-runtime.test.mjs
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• scripts/__tests__/registry-install-smoke-security.test.mjs
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• scripts/__tests__/zip-archive.test.mjs
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts
• docs/local-runtime-state-contract.md
• scripts/__tests__/release-portable-prerelease.test.mjs
• docs/adr/ADR-0121-portable-managed-install-and-release-asset-update-authority.md
• scripts/release-publish.mjs
• scripts/lib/portable-release-verification.mjs
• release-impact.catalog.json
• scripts/lib/zip-archive.mjs
• scripts/release-portable-prerelease.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Preserve the human-control invariant: never weaken authority validation, trust boundaries, evidence redaction, governance gates, or fail-closed behavior.
Match naming, error handling, evidence redaction, and test style used by neighboring files in the same package.
Delete dead code rather than commenting it out; do not leave scaffolding or TODOs hiding unfinished branches.
Use English in code, comments, identifiers, documentation, commit messages, issues, and pull requests.
Inspect and reuse existing helpers, contracts, and subsystems before building; do not introduce parallel workspace, graph, policy, evidence, memory, connector, workflow, or UI subsystems without a documented capability gap.
Work on a non-dev branch named type/short-slug; never work directly on dev.
Use signed, imperative conventional commit subjects with a PR or issue reference, in English and without secrets.

Files:

• docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md
• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• scripts/__tests__/portable-runtime.test.mjs
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• scripts/__tests__/registry-install-smoke-security.test.mjs
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• scripts/__tests__/zip-archive.test.mjs
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts
• docs/local-runtime-state-contract.md
• scripts/__tests__/release-portable-prerelease.test.mjs
• docs/adr/ADR-0121-portable-managed-install-and-release-asset-update-authority.md
• scripts/release-publish.mjs
• scripts/lib/portable-release-verification.mjs
• release-impact.catalog.json
• scripts/lib/zip-archive.mjs
• scripts/release-portable-prerelease.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs

**/*.{ts,tsx,mjs,js,json,yml,yaml,md}

📄 CodeRabbit inference engine (AGENTS.md)

Keep secrets out of code, logs, evidence, configuration, tests, manifests, and diagnostics; evidence must contain only redacted counts, hashes, statuses, scopes, or summaries, never raw content, keys, endpoints, or PII.

Files:

• docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md
• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• scripts/__tests__/portable-runtime.test.mjs
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• scripts/__tests__/registry-install-smoke-security.test.mjs
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• scripts/__tests__/zip-archive.test.mjs
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts
• docs/local-runtime-state-contract.md
• scripts/__tests__/release-portable-prerelease.test.mjs
• docs/adr/ADR-0121-portable-managed-install-and-release-asset-update-authority.md
• scripts/release-publish.mjs
• scripts/lib/portable-release-verification.mjs
• release-impact.catalog.json
• scripts/lib/zip-archive.mjs
• scripts/release-portable-prerelease.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs

docs/adr/ADR-*.md

📄 CodeRabbit inference engine (AGENTS.md)

Read relevant ADRs before changing boundaries, update affected sections when recorded behavior becomes outdated or unsafe, add genuinely new ADRs using the next free number, register them in the index, and never renumber existing ADRs.

Files:

• docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md
• docs/adr/ADR-0121-portable-managed-install-and-release-asset-update-authority.md

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx}: Use TypeScript strict settings, avoid any, provide explicit function return types, model states with discriminated unions, and narrow values instead of casting.
Keep cyclomatic complexity at most 10 and each function at most 50 non-comment, non-blank lines; extract helpers when necessary.
Do not use console.* for real product output; route output through the intended logger or diagnostic sink.
Fix bugs at the layer that owns the invariant and address the whole class of bug rather than patching individual call sites.
Do not silently swallow errors; avoid empty catches, provide diagnostic context, and include a correlation ID for server errors connecting opaque UI 500 responses to redacted operator diagnostics.
Validate hostile workspace input, model output, and connector data before processing; generated code must remain behind the sandbox egress boundary.
Keep tests hermetic: no real network, shared mutable global state, wall-clock or ordering races, or reliance on an available port; await conditions instead of sleeping and use deterministic self-contained fixtures.
Keep coverage from falling below the committed per-file baseline; add tests for new code and do not add competing Vitest thresholds or hard-coded coverage values.

Files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

**/*.{ts,tsx,mjs,js}

📄 CodeRabbit inference engine (AGENTS.md)

Use Prettier formatting: 2-space indentation, double quotes, semicolons, 100-column print width, trailing commas, and LF endings.

Files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• scripts/__tests__/portable-runtime.test.mjs
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• scripts/__tests__/registry-install-smoke-security.test.mjs
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• scripts/__tests__/zip-archive.test.mjs
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts
• scripts/__tests__/release-portable-prerelease.test.mjs
• scripts/release-publish.mjs
• scripts/lib/portable-release-verification.mjs
• scripts/lib/zip-archive.mjs
• scripts/release-portable-prerelease.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs

packages/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

Maintain package dependency direction: keiko-contracts is the leaf, security depends only on contracts, domain packages must not depend on the server, and the server must not depend on keiko-editor.

Files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

**/*.test.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.test.{ts,tsx}: Regression tests must fail before the fix and pass afterward; fixtures and mocks must call or derive from the production entry point rather than reimplementing its formula.
Test empty, boundary, malformed, and hostile inputs, including both branches of every guard introduced.

Files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

packages/**/src/**

⚙️ CodeRabbit configuration file

packages/**/src/**: Enforce ADR-0019 package direction and the owning trust boundary. Flag provider SDK imports
outside keiko-model-gateway, cross-package wire types outside contracts, workspace escape,
raw evidence bodies, silent failures, and parallel subsystems that should extend an owner.

Files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

**/*.test.{ts,tsx,mjs}

⚙️ CodeRabbit configuration file

**/*.test.{ts,tsx,mjs}: A behavioral fix needs a failure-first regression proof that fails without the fix. Cover
malformed, hostile, empty, and boundary inputs; never relax a regression pin or duplicate a
production formula inside a fixture.

Files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• scripts/__tests__/portable-runtime.test.mjs
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• scripts/__tests__/registry-install-smoke-security.test.mjs
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• scripts/__tests__/zip-archive.test.mjs
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts
• scripts/__tests__/release-portable-prerelease.test.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs

scripts/**

⚙️ CodeRabbit configuration file

scripts/**: Gate and evidence tooling must fail closed, remain deterministic and redacted, and carry
negative tests proving that weakened configuration or stale evidence is rejected.

Files:

• scripts/__tests__/portable-runtime.test.mjs
• scripts/__tests__/registry-install-smoke-security.test.mjs
• scripts/__tests__/zip-archive.test.mjs
• scripts/__tests__/release-portable-prerelease.test.mjs
• scripts/release-publish.mjs
• scripts/lib/portable-release-verification.mjs
• scripts/lib/zip-archive.mjs
• scripts/release-portable-prerelease.mjs
• scripts/__tests__/portable-release-verification.test.mjs
• scripts/__tests__/release-publish-pipeline.test.mjs

packages/keiko-model-gateway/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Provider SDKs such as openai, @anthropic-ai/*, and *-ai-sdk may be imported only by keiko-model-gateway.

Files:

• packages/keiko-model-gateway/src/index.test.ts

.github/workflows/**

📄 CodeRabbit inference engine (AGENTS.md)

Never push directly to dev, force-push, bypass required checks, dismiss findings to obtain green status, or merge outside the ADR-0135 direct-check path.

Files:

• .github/workflows/portable-assets.yml

---

⚙️ CodeRabbit configuration file

.github/workflows/**: Treat workflow changes as supply-chain and merge-authority changes. Require full 40-hex
action pins with version comments, minimum permissions, bounded timeouts, locked installs,
redacted output, and exact-current-head evidence. Never recommend bypassing a gate.

Files:

• .github/workflows/portable-assets.yml

.github/workflows/**/*.{yml,yaml}

📄 CodeRabbit inference engine (AGENTS.md)

Pin every GitHub Action to a full 40-character commit SHA with a version comment; tag and branch references are prohibited.

Files:

• .github/workflows/portable-assets.yml

🧠 Learnings (4)

📚 Learning: 2026-07-25T18:42:13.123Z

Learnt from: oscharko
Repo: oscharko-dev/Keiko PR: 2716
File: packages/keiko-tools/src/editor-agent-client.test.ts:692-692
Timestamp: 2026-07-25T18:42:13.123Z
Learning: In Keiko TypeScript test files, do not request explicit return type annotations for callbacks passed to typed Vitest `it(...)` and `it.each(...)`. Specifically, avoid adding `: void` or `: Promise<void>` to those callback functions when the ESLint rule `typescript-eslint/explicit-function-return-type` is configured with `allowTypedFunctionExpressions: true` (i.e., typed function expressions are intentionally exempt). Only ask for explicit return types if the ESLint configuration changes; otherwise preserve the existing surrounding test-file style.

Applied to files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

📚 Learning: 2026-07-27T10:55:30.485Z

Learnt from: oscharko
Repo: oscharko-dev/Keiko PR: 2766
File: packages/keiko-server/src/qualityIntelligence/figmaSnapshotRoutes.test.ts:1738-1738
Timestamp: 2026-07-27T10:55:30.485Z
Learning: When reviewing TypeScript files, do not flag single-quoted string literals as a violation if they match Prettier’s formatter-approved output. Specifically, if Prettier is configured to prefer double quotes but retains a single-quoted literal solely because switching to double quotes would require escaping embedded double quotes, allow the single quotes (i.e., don’t “fix” it beyond what Prettier would produce).

Applied to files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

📚 Learning: 2026-07-27T18:08:22.461Z

Learnt from: oscharko
Repo: oscharko-dev/Keiko PR: 2780
File: packages/keiko-server/src/store/migrations.test.ts:78-95
Timestamp: 2026-07-27T18:08:22.461Z
Learning: When reviewing TypeScript lint findings (e.g., from typescript-eslint/no-unsafe-assignment), ensure the issue is reproducible using the repository’s configured ESLint setup/TS project settings. Do not treat diagnostics observed under a mismatched TypeScript project/tsconfig as authoritative; only accept them as real if you can reproduce them with the same ESLint configuration the repo uses (e.g., via its full/targeted lint scripts). In related test code, prefer deriving branded identity types from the production function return types to keep RootIdentity/brand fields type-compatible and avoid unsafe assignments.

Applied to files:

• packages/keiko-memory-retrieval/src/version.test.ts
• packages/keiko-memory-retrieval/src/index.test.ts
• packages/keiko-tools/src/version.test.ts
• packages/keiko-security/src/index.test.ts
• packages/keiko-memory-governance/src/index.test.ts
• packages/keiko-memory-consolidation/src/version.test.ts
• packages/keiko-contracts/src/index.test.ts
• packages/keiko-workspace/src/index.test.ts
• packages/keiko-model-gateway/src/index.test.ts
• packages/keiko-tools/src/index.test.ts
• packages/keiko-memory-governance/src/version.test.ts
• packages/keiko-harness/src/index.test.ts
• packages/keiko-evidence/src/index.test.ts
• packages/keiko-memory-consolidation/src/index.test.ts

📚 Learning: 2026-07-26T21:23:56.288Z

Learnt from: oscharko
Repo: oscharko-dev/Keiko PR: 2755
File: packages/keiko-server/src/grounded-qa-hybrid.ts:1006-1012
Timestamp: 2026-07-26T21:23:56.288Z
Learning: In Keiko’s internal “stable-ID” hash helper functions (e.g., where stable identifiers are computed for persistence/comparison), preserve the existing UTF-16 code-unit iteration semantics when modernizing. Specifically, if the current implementation iterates with `charCodeAt(i)` (code units) rather than `codePointAt(i)` (Unicode code points), keep `charCodeAt(i)` to avoid changing the resulting stable IDs. If changing from `charCodeAt` to `codePointAt` is ever desired, it must be an explicitly planned compatibility/migration decision (e.g., versioning, backfill, or dual-read/write) rather than a mechanical refactor.

Applied to files:

• packages/keiko-contracts/src/index.test.ts

🪛 LanguageTool

docs/adr/ADR-0130-npm-trusted-publishing-for-release-pipeline.md

[style] ~66-~66: Consider an alternative for the overused word “exactly”.
Context: ... npm@11.16.0 ``` The pinned version is exactly the governed EXPECTED_PACKAGE_MANAGER...

(EXACTLY_PRECISELY)

🔇 Additional comments (19)

scripts/lib/portable-release-verification.mjs (2)

466-479: The repository is now threaded through every artifact read.

declaredArtifactRecordVerified builds the path from the verified repository instead of letting gh expand {owner}/{repo} from the checkout remote, and scripts/release-publish.mjs forwards the same identity into the adapter. This resolves the earlier finding.

Also applies to: 509-519

---

162-168: 🔒 Security & Privacy

No change needed: manifest completeness already fails closed.

portableReleaseFailures stops before declaredDownloads when portableEvaluationManifestFailures(manifest, ...) reports missing assets, so the remaining checks never run for the omitted download.

			> Likely an incorrect or invalid review comment.

.github/workflows/portable-assets.yml (2)

46-71: The scope job fails closed, and the jq expression is safe.

The tag reaches jq through --arg, so a hostile tag name cannot alter the filter. A missing entry, a missing portableRuntimeArtifactContract, or an empty entries array all resolve to production=true. A missing or malformed release-impact.catalog.json makes jq exit non-zero, which fails the step under the default bash -e shell and leaves the run red instead of publishing unsigned assets.

Permissions, the 40-hex action pin with its version comment, and the 5-minute timeout all match the workflow rules for this path.

---

72-75: 🩺 Stability & Availability

No change needed. production-signing-preflight is not in RELEASE_REQUIRED_CHECKS, and evaluation-scoped tags skip production staging by design.

</verification Result>

<!-- cr-comment:v1:607b1053c58d504167f671a0 -->

</blockquote></details>
<details>
<summary>scripts/lib/zip-archive.mjs (1)</summary><blockquote>

`290-317`: **The structural guards and the descriptor lifetime are correct.**

`endOfCentralDirectoryOffset` scans backwards and cannot run past the buffer start, because a file shorter than 22 bytes produces a negative start offset and the loop body never runs. `readCentralEntry` bounds-checks its 46-byte header and validates the signature, so a bad `next` value throws on the following iteration. `readAt` treats a zero-length read as truncation. `extractZipArchiveEntries` closes the descriptor in `finally` on every path, and `normalizedEntryName` is called without `allowUnsafeEntryNames`, so a traversal name throws before `writeFileSync` runs.



Also applies to: 376-385, 415-418, 437-439

<!-- cr-comment:v1:42db1953f265faf9482fb217 -->

</blockquote></details>
<details>
<summary>scripts/__tests__/portable-release-verification.test.mjs (1)</summary><blockquote>

`607-823`: **The artifact-digest suite covers the hostile cases well.**

The cases pin a foreign artifact id, a renamed record, a foreign run id, an expired record, an unreadable record, a malformed archive, a fetch failure, temporary-directory cleanup, the same-named evidence-file case from the 0.3.1 outage, and a genuine digest disagreement. The rerun case at lines 701-723 throws when the mutable artifact listing is consulted, which pins the immutable-id contract directly.



Also applies to: 825-905

<!-- cr-comment:v1:115046423920c12b5681d476 -->

</blockquote></details>
<details>
<summary>scripts/__tests__/zip-archive.test.mjs (1)</summary><blockquote>

`236-330`: **The reader suite now pins each branch of `inflatedEntryData` and the tamper message.**

The tamper case asserts the declared-size-or-checksum message, the stored case exercises method 0 through hand-built bytes, and the unsupported case exercises method 12. The traversal case uses `allowUnsafeEntryNames` on the writer to produce a hostile archive, which keeps the fixture derived from the production writer.

<!-- cr-comment:v1:defa4f3eeec310e3e271377b -->

</blockquote></details>
<details>
<summary>docs/local-runtime-state-contract.md (1)</summary><blockquote>

`4-7`: **Include 0.3.2 in the unchanged-state range.**

Line 7 stops at `0.3.1`, although Lines 4-6 state that `0.3.2` changes none of this contract. State `0.3.0 through 0.3.2`.

<!-- cr-comment:v1:355bf68763e235a4b43c9cf4 -->

</blockquote></details>
<details>
<summary>scripts/__tests__/release-portable-prerelease.test.mjs (1)</summary><blockquote>

`493-505`: **Assert the evaluation manifest bindings.**

This test only checks that the manifest filename reaches `gh release create`. Snapshot and parse the temporary manifest. Assert its workflow attempt, immutable artifact IDs, and asset digests. A malformed manifest can otherwise reach the release while the npm publisher later refuses it.

<!-- cr-comment:v1:c389f070e57f9b22d7e36470 -->

</blockquote></details>
<details>
<summary>packages/keiko-tools/src/version.test.ts (2)</summary><blockquote>

`12-14`: **Update the stale test description.**

Line 13 says the test checks the literal `0.3.1`, but Line 14 compares `KEIKO_TOOLS_VERSION` with `packageVersion`. Rename the case to describe the manifest synchronization, such as `matches the packaged manifest version`. This finding was already raised in the previous review.

<!-- cr-comment:v1:05d49e8a2cfb318963b6651c -->

---

`2-10`: LGTM!

<!-- cr-comment:v1:11c3cd70304f6743b99bf693 -->

</blockquote></details>
<details>
<summary>packages/keiko-contracts/src/index.test.ts (1)</summary><blockquote>

`2-3`: LGTM!



Also applies to: 188-193, 200-201

<!-- cr-comment:v1:2fb8f07afb4a2f75869b0f9c -->

</blockquote></details>
<details>
<summary>packages/keiko-evidence/src/index.test.ts (1)</summary><blockquote>

`9-10`: LGTM!



Also applies to: 60-68

<!-- cr-comment:v1:b867c849455a7ccc8198f6fe -->

</blockquote></details>
<details>
<summary>packages/keiko-harness/src/index.test.ts (1)</summary><blockquote>

`13-14`: LGTM!



Also applies to: 66-76

<!-- cr-comment:v1:f538d65d8f97cefdf322bda2 -->

</blockquote></details>
<details>
<summary>packages/keiko-memory-consolidation/src/index.test.ts (1)</summary><blockquote>

`11-12`: LGTM!



Also applies to: 42-46, 52-54

<!-- cr-comment:v1:d2ebdaa0c4ae48b92b49439f -->

</blockquote></details>
<details>
<summary>packages/keiko-tools/src/index.test.ts (1)</summary><blockquote>

`8-9`: LGTM!



Also applies to: 106-114

<!-- cr-comment:v1:7423fb17d5bcfac1fa145e9d -->

</blockquote></details>
<details>
<summary>packages/keiko-workspace/src/index.test.ts (1)</summary><blockquote>

`8-20`: LGTM!

<!-- cr-comment:v1:ccc1a3b331c3ab4a0e58a89a -->

</blockquote></details>
<details>
<summary>packages/keiko-memory-retrieval/src/version.test.ts (1)</summary><blockquote>

`14-15`: **Rename the stale version in the test title.**

Line 14 still says `0.3.1`, while line 15 compares `KEIKO_MEMORY_RETRIEVAL_VERSION` with `packageVersion`. Rename the title to describe the package-manifest comparison. The previous review raised the same finding, and the stale text remains.

<!-- cr-comment:v1:f3400674e1b0fbcedd176618 -->

</blockquote></details>
<details>
<summary>packages/keiko-memory-consolidation/src/version.test.ts (1)</summary><blockquote>

`9-11`: _📐 Maintainability & Code Quality_

The unchecked manifest assertion no longer remains in the listed test files. If the review should also address helper reuse, inspect whether a shared test helper is available.

<!-- cr-comment:v1:602743416b247ac98847223b -->

</blockquote></details>

</blockquote></details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->