feat(contracts): add component metadata v1 - #320
Conversation
![baz-reviewer[bot]](https://avatars.githubusercontent.com/in/933528?s=60&v=4){kind=small}
| "provides": { | ||
| "type": "array", | ||
| "minItems": 1, | ||
| "uniqueItems": true, | ||
| "items": { | ||
| "type": "string", | ||
| "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" | ||
| } | ||
| }, | ||
| "management_protocol_provides": { | ||
| "type": "array", | ||
| "uniqueItems": true, |
There was a problem hiding this comment.
Role topology is unenforced
clawsec.role isn't used to constrain the dependency fields here, so suite, guardian, and core metadata can still satisfy the array syntax while violating the PR contract — should we add role-specific if/then rules for the intended dependency shape?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
contracts/schemas/component/metadata-v1.schema.json around lines 123-159 within the
`clawsec` object (the `provides`, `management_protocol_provides`,
`management_protocol_requires`, `install_requires`, and `runtime_requires` definitions),
add role-specific validation that actually uses `clawsec.role` to constrain these
fields. Refactor the existing `clawsec.allOf` section (currently only enforcing the
guardian family/default_mode rules around lines 176-211) by adding additional `if/then`
branches: for `core`, require `management_protocol_provides` (and keep array syntax
validation); for `suite`, forbid `runtime_requires` (or require it to be absent/empty
per the PR contract); and for `guardian`, forbid `runtime_requires` as well. Make the
rules explicit using `required`/`not` so the schema can no longer accept metadata
combinations that the finding calls out.
There was a problem hiding this comment.
Commit 8216ac5 addressed this comment by adding role-aware topology validation in validateRoleGraph, enforcing core, suite, and guardian dependency/protocol shapes. The JSON schema itself still lacks equivalent if/then rules, so schema-only consumers can accept invalid combinations.
| if (!validateMetadataSchema(skill)) { | ||
| for (const schemaError of validateMetadataSchema.errors ?? []) { | ||
| addError( | ||
| errors, | ||
| "METADATA_SCHEMA_INVALID", | ||
| schemaError.dataPath || "/", | ||
| `${schemaError.keyword}: ${schemaError.message}`, | ||
| ); | ||
| } | ||
| return finish("invalid", errors, warnings); |
There was a problem hiding this comment.
Schema diagnostics drift between validators
validateClawsecMetadata() and validateComponentRef() both repeat the same validate*.errors loop and diagnostic shaping (schemaError.dataPath || "/", ${schemaError.keyword}: ${schemaError.message}), so any future error-format tweak has to be made twice and can drift — should we factor that into a tiny local helper?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
scripts/ci/validate_clawsec_metadata.mjs around lines 89-99 inside
validateClawsecMetadata and around lines 215-225 inside validateComponentRef, both
validators duplicate the same AJV error-to-diagnostic loop and formatting
(`schemaError.dataPath || "/"` and ``${schemaError.keyword}: ${schemaError.message}``).
Refactor this by introducing a tiny local helper (near the two validators) that accepts
the validator failure + the error array and an error code, then loops over
`validator.errors ?? []` and calls addError with the common path/message shaping. Update
both validators to call this helper instead of inlining the loop so the
schema-to-diagnostic contract lives in one place.
1 participant
User description
Summary
clawsecmetadata schema for canonical core, suite, and drift-guardian packages.clawsec-core/v1management protocol..claude/skills/packages and reject v1 metadata, unsafe placement, invalid persistence, and statefuloperationalsuites.Architecture alignment
This implements the bounded
metadata-contracts-v1unit from design PR #306 and is stacked on strict lifecycle SemVer PR #309.The contract preserves the intended dependency direction:
maturityis a package capability claim, not the beta/RC/stable release lifecycle.stableanddeprecatedremain structural vocabulary only; this validator does not prove conformance, qualification, successor authorization, or catalog activation.The fixtures use
0.1.0-rc.1and deliberately state that they are contract fixtures, not harness-support claims.suite.recurring-advisory-verificationis optional so NanoClaw v2 can truthfully omit it and later reportintentionally_unsupportedthrough the result contract.The component reference validates identity and digest syntax only. Later result, receipt, and catalog verifiers must recompute the digest against exact
skill.jsonbytes.Scope boundaries
This PR does not:
stablemetadata without later conformance and signed-catalog evidence.Remote verification
The exact pushed files were copied with SCP to an operator-approved remote Linux lab checkout at base
2293a80b752325b06515244c2ee7a33118ba5367. Local and remote SHA-256 values matched for all 14 changed files.Passed remotely:
npm run test:metadata-contracts— 6 valid fixtures and 42 invalid fixturesscripts/test-skill-*.mjsregressionnpx tsc --noEmitnpm run buildutils/git diff --checkTwo independent read-only reviews accepted the frozen hash set after the blocking findings were corrected.
Review state
Keep this PR in draft. Do not merge it until PR #306, PR #309, the skill SemVer rules, and the shared design language are reviewed together.
Generated description
Below is a concise technical summary of the changes proposed in this PR:
Add normalized
clawsecmetadata v1 by introducing the package metadata schema, component-reference schema, and capability registry for canonicalcore,suite, andguardianpackages. Extend the Node validator and Pythonvalidate_skill.pywrapper to enforce identity, dependency direction, and NanoClaw v2 host placement while classifying non-normalized packages as legacy migration inputs.clawsecv1 contract for canonical package identity, supported capabilities, and component-reference syntax acrosscore,suite, and driftguardianpackages.Modified files (9)
Latest Contributors(1)
Modified files (5)
Latest Contributors(2)