Add experimental portable Claw package schema

[giodl73-repo]

Summary

• Defines the strict portable Claw v1 manifest and bounded public summary.
• Keeps agent limited to identity and purpose.
• Adds opaque string metadata and validates openclaw.config as a forward-slash package-relative YAML pointer.
• Adds family: "claw" to storage while keeping publication closed until Add gated Claw publication and profile validation #3090.
• Preserves strict portable paths, exact package coordinates, MCP declarations, cron declarations, and bounded images.

This is ClawHub PR 1 of 4 for merged OpenClaw RFC #27, updated for the portable-core boundary in RFC #48 and OpenClaw #112773.

The manifest does not embed OpenClaw policy. metadata.openclaw.config points to a package-local profile; unknown metadata remains opaque. This slice validates pointer syntax only. #3090 owns validation of the referenced artifact.

Experimental boundary

This PR exposes no publication, discovery, feed, or UI surface. Later surfaces require CLAWHUB_EXPERIMENTAL_CLAWS=1. The gate is not user consent and does not replace OpenClaw plan-integrity confirmation.

Stack

1. Add experimental portable Claw package schema #3089: portable schema and storage
2. Add gated Claw publication and profile validation #3090: gated publication and profile validation
3. Add gated Claw discovery and API projection #3091: gated discovery APIs
4. Add gated Claw hosted feed and lifecycle proof #3092: hosted feed and OpenClaw bridge proof

Validation

• 27/27 focused manifest tests pass.
• Schema build and schema typecheck pass.
• Type-aware Oxlint reports zero findings.
• Formatting and git diff --check pass.
• Final Codex review reports no actionable defects.
• Signed head: 61bc0f49759c.

No live Convex deployment was modified.

[vercel]

@giodl73-repo is attempting to deploy a commit to the OpenClaw Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 22, 2026, 1:32 AM ET / 05:32 UTC.

Summary
The PR adds an experimental claw package-family schema, Convex release-storage fields, generated schema exports, and focused manifest-contract tests while keeping generic publication closed.

Reproducibility: not applicable. This PR introduces a new experimental package-family capability rather than fixing a currently broken behavior. Its submitted terminal proof provides a credible after-fix validator and schema-load path.

Review metrics: 2 noteworthy metrics.

• Patch footprint: 19 files affected; 2,408 added, 20 removed. Most of the change is a new exported validation contract and committed build output, so the compatibility decision spans more than one isolated schema field.
• Focused contract coverage: 23 focused tests reported. The submitted proof exercises validator acceptance, bounded summary projection, and generic-publication exclusion for the new family.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Obtain explicit maintainer sponsorship for the persistent experimental package-family contract.
• Rebase onto current main and refresh the clean-merge review after sponsorship.

Risk before merge

• [P1] Merging would expand the public PackageFamily union and persist claw releases before maintainers have accepted the experimental registry’s compatibility, migration, and eventual ungating policy.
• [P1] The branch is draft and GitHub reports a dirty merge state, so the sponsor-approved version needs a rebase and an updated merge review before landing.

Maintainer options:

1. Sponsor and refresh the experimental contract (recommended)
   Before merge, confirm the intended compatibility/versioning policy for the new persisted family, then rebase the draft and rerun the contract and schema checks.
2. Defer durable storage changes
   Pause this PR if maintainers do not yet want old clients and future migrations to carry the experimental claw family contract.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Rebase onto current main after sponsorship, preserve generic publication exclusion, and rerun the focused Claw schema tests plus schema/type checks.

Next step before merge

• [P2] A maintainer must make the explicit product and compatibility decision; there is no narrow mechanical repair for ClawSweeper to apply.

Maintainer decision needed

• Question: Should ClawHub adopt and version this staged experimental claw package-family storage contract before the gated publication, discovery, and feed work is ready to land?
• Rationale: The implementation is intentionally a durable cross-surface contract, not a bug fix; accepting its storage and public type expansion determines future client compatibility, migration, and experimental-gate policy.
• Likely owner: giodl73-repo — They can provide the RFC-aligned contract rationale and coordinate the dependent stack, while a repository sponsor makes the final product decision.
• Options:
  • Sponsor the staged contract (recommended): Accept the experimental storage contract, require a refreshed clean merge result, and review the dependent gated slices in stack order.
  • Pause the rollout: Keep the draft stack open but do not merge persistent claw storage or public family typing until maintainers choose a narrower or differently versioned registry design.

Security
Cleared: The patch adds validation and storage contracts but does not introduce an execution path, broaden repository permissions, or alter CI/release automation; the new locked croner dependency is directly used for cron validation and was reported without a Socket advisory.

Review details

Best possible solution:

Obtain explicit sponsorship for the staged experimental registry contract, including its compatibility/versioning and future gate-removal policy; then rebase this foundation and land the stack in its declared order while generic publication remains closed.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR introduces a new experimental package-family capability rather than fixing a currently broken behavior. Its submitted terminal proof provides a credible after-fix validator and schema-load path.

Is this the best way to solve the issue?

Unclear pending sponsorship: the staged boundary is technically narrow and keeps generic publication closed, but maintainers must first accept the durable storage and compatibility contract that the later stack will build on.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a9775fc39b10.

Label changes

Label justifications:

• P3: This is an experimental feature foundation with no reported user-facing outage, but it merits a deliberate sponsorship decision.
• merge-risk: 🚨 compatibility: The PR expands a public package-family union and persists a new release family whose long-term versioning and migration policy is not yet maintainer-confirmed.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR provides after-fix terminal evidence from a real built schema distribution and a real Convex schema-module load, alongside focused validator tests; no browser or deployed-service proof is needed for this intentionally storage-only slice.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR provides after-fix terminal evidence from a real built schema distribution and a real Convex schema-module load, alongside focused validator tests; no browser or deployed-service proof is needed for this intentionally storage-only slice.

Evidence reviewed

What I checked:

• Current-main status: The PR remains open, draft, and unmerged at dd5fef7f8dc5; the supplied current-main SHA is a9775fc39b10016613441a7d685c34932b5071fc, so current main does not contain this branch’s experimental Claw schema/storage implementation. (a9775fc39b10)
• Persistent contract surface: The branch adds claw to the package-family validator and stores an extracted Claw manifest plus a bounded summary on package releases, creating a durable schema and API contract rather than an isolated helper. (convex/schema.ts:513, dd5fef7f8dc5)
• Publication remains deliberately closed: The source separates the storage-wide PackageFamilySchema from PackagePublishFamilySchema, preserving the existing generic publication boundary until a dedicated validation and feature-gate path lands. (packages/schema/src/packages.ts:29, dd5fef7f8dc5)
• Contract intent and stack boundary: The branch’s design note describes this as stage 1 of a four-stage experimental Claw rollout and says gate removal needs a separate compatibility and migration decision; the dependent publication, discovery, and feed PRs remain open at Add gated Claw publication and profile validation #3090, Add gated Claw discovery and API projection #3091, and Add gated Claw hosted feed and lifecycle proof #3092. (specs/claws.md:1, dd5fef7f8dc5)
• Focused after-fix proof: The PR body reports a built clawhub-schema distribution and real convex/schema.ts module load, with 23 focused manifest tests plus schema build, root typecheck, and type-aware lint; the focused contract coverage is in the branch. (packages/schema/src/claws.test.ts:1, dd5fef7f8dc5)

Likely related people:

• giodl73-repo: Authored the current schema/storage commit and the linked staged publication, discovery, and hosted-feed proposals, making them the best available routing contact for contract context; repository sponsorship remains a separate maintainer decision. (role: experimental contract author and stack coordinator; confidence: medium; commits: dd5fef7f8dc5; files: packages/schema/src/claws.ts, packages/schema/src/packages.ts, convex/schema.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (4 earlier review cycles)

• reviewed 2026-07-16T10:25:28.113Z sha 0087aea8cc0263a31d44eb6427b01d0dbdcfd4b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-17T05:25:09.939Z sha 821c1f4e91e6efc2a50dfdfe2e00e9b754e781be :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T10:06:24.417Z sha 821c1f4e91e6efc2a50dfdfe2e00e9b754e781be :: needs real behavior proof before merge. :: none
• reviewed 2026-07-20T02:11:13.996Z sha a23ebf6113d5092d5166038e07d3c18adadee0c3 :: needs maintainer review before merge. :: none

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	croner@​10.0.1

View full report

[giodl73-repo]

Updated at 821c1f4 after merging current main. The shared schema now matches the RFC sidecars for managed avatars, normalized workspace collisions, exact package-kind identity, Claw heartbeat/delay fields, portable MCP declarations, and five-field timezone-bound cron jobs without current-session leakage. The review-found multi---package bypass is fixed by validating every -p/--package selector. Proof: 23 focused tests, full ci:static and ci:types-build, built-schema plus Convex-schema positive/negative consumer runs, and a clean final Codex branch review. The PR body explicitly notes that no reusable local Convex backend was available rather than overstating that proof.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

Refreshed this first slice onto current ClawHub main at �23ebf61. It now matches the final RFC/OpenClaw contract for strict strings, package-manager selection, blocked process env keys, tool-filter syntax, generic bounded image data URLs, and package uniqueness by kind. Focused schema tests/build/type/lint pass; the PR body now includes an inspectable built-schema/Convex load transcript.

[giodl73-repo]

@clawsweeper re-review

[giodl73-repo]

Final current-main refresh is at �23ebf6113d5. This foundation now enforces the RFC's strict Claw schema, bounded safe-summary contract, exact package-kind identity, full spawned-process environment-key policy, safe workspace/avatar limits, and experimental package-family storage. Focused schema tests (22), schema build/type/lint/format/diff checks, and built consumer plus Convex-schema load proof pass. The cumulative four-PR Codex review is clean.

[giodl73-repo]

@clawsweeper re-review

[giodl73-repo]

Independent three-agent review fixes are applied at 34f3cbea35dc: package-manager invocation handling now covers npm exec/npm x and bun x, unsupported known modes fail closed, public summary text is bounded, and the CI-reported shadowed binding is fixed. Current-head proof: 23 focused schema tests, schema build, root typecheck, type-aware lint, format, and diff checks pass. RFC #27 and its sidecars are updated: openclaw/rfcs#27

[giodl73-repo]

Final exact-head correction: dd5fef7f8dc5 includes the regenerated schema distribution after the lint-only summary-binding rename; downstream commits were re-signed and restacked with no behavior change. The cumulative schema build is now clean with no generated-file drift.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

Rebased onto current ClawHub main and synchronized the manifest contract with the current OpenClaw stack plus portable agent-settings addendum RFC #48. ClawHub validates portable profile/modifier structure without freezing OpenClaw's built-in profile registry; the applying OpenClaw version resolves the selected profile before planning mutation.

Exact head: 58b53c7. Focused schema tests pass 25/25; schema build, root typecheck, type-aware lint, format, and diff checks pass. The commit is signed and the PR is mergeable.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: Add experimental Claw package schema This is item 1/1 in the current shard. Shard 15/22.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[giodl73-repo]

Synced to the portable-core boundary from RFC #48: agent now carries only identity/purpose, metadata is a string map, and the recognized openclaw.config pointer is path-validated without embedding OpenClaw policy. Signed head 680cc6b9e91b; 26/26 focused tests and final Codex review are clean.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[giodl73-repo]

Rebased the full stack onto current ClawHub main at edd4e01. This PR is now at signed head 6b9a1d008380; focused schema proof remains green. @clawsweeper re-review

[giodl73-repo]

Portable pointer follow-up is fixed at signed head 61bc0f49759c: metadata.openclaw.config now rejects backslashes and requires forward-slash package-relative YAML syntax. Validation includes 27/27 focused tests, schema typecheck/build, lint, formatting/diff checks, and a clean Codex review.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.