config_schema is now required for every plugin that requests config_read (all 31 packages)

[JordanTheJet]

What is changing

ZeroClaw is adding typed, schema-validated plugin config (host PR zeroclaw-labs/zeroclaw#9126). Once it lands, a manifest that requests config_read without declaring config_schema is no longer discovered or installed. The two are a biconditional: declaring a schema without requesting the permission is equally invalid.

This ships without a compatibility shim or grace period. Plugins are a pre-1.0 experimental surface, and an untyped fallback would have to hand a guest values the host cannot type, name, or bound, which is the hole the feature closes. Packages that do not migrate stop being discovered; nothing is silently downgraded.

Every package in this repository requests config_read and none declares config_schema today, so all 31 need migration.

Why the host needs the schema

Operator values are stored as a secret-marked string map, encrypted at rest, and the guest is untrusted code. Before starting a guest the host must know which keys the package may receive and what type each value is. The WIT worlds are fixed and shared across all plugins, so per-package config types cannot live in the ABI. The manifest is the only place the contract can be declared, and additionalProperties = false plus an explicit properties map is what makes the config_read grant enumerable.

What each package needs

Full recipe with examples, limits, and error messages: Migrating to typed plugin config.

Short version, per package:

1. Add a closed Draft 2020-12 [config_schema] to manifest.toml covering exactly the keys the plugin reads. Root must be type = "object" with additionalProperties = false; every top-level property needs one explicit type from string, boolean, integer, number, array, object.
2. Mark credentials required so a withheld grant fails closed instead of starting half-configured. Optional keys receive {} when the grant is withheld, so give them guest-side defaults.
3. Update the guest to deserialize the injected typed JSON once instead of parsing strings. Booleans, numbers, arrays, and objects arrive as real JSON values.
4. Rebuild the component.
5. Re-sign, if the package is signed: config_schema is covered by the manifest signature.

permissions = ["config_read"]

[config_schema]
"$schema" = "https://json-schema.org/draft/2020-12/schema"
type = "object"
required = ["bot_token"]
additionalProperties = false

[config_schema.properties.bot_token]
type = "string"
minLength = 1

[config_schema.properties.poll_interval_secs]
type = "integer"
minimum = 1

Schema limits enforced by the host: 64 KiB serialized, at most 32 levels of nesting, no $id, and $ref must be a local JSON Pointer. Remote references are rejected, so a schema never triggers a network fetch.

Operator-facing change in the same release

[[plugins.entries]] is now keyed by a full-instance key derived from package, capability, and binding (zpi1_...) rather than the package or binding name. Legacy entries are not consulted. zeroclaw plugin info <package> prints the key; fresh installs seed and print it automatically. Worth a line in each package's README where it documents configuration.

Checklist

• amqp
• bluesky
• dingtalk
• discord
• email
• gitea
• gmail_push
• irc
• lark
• line
• linq
• matrix
• mattermost
• mochat
• mqtt
• nextcloud
• nostr
• notion
• qq
• redact-text
• reddit
• slack
• telegram
• twitch
• twitter
• wati
• webhook
• wechat
• wecom
• wecom-ws
• whatsapp

[JordanTheJet]

Rollout scope correction: 31 source manifests, 12 published names, 24 immutable registry entries

The checklist above counts source manifests. The published surface is narrower and behaves differently, so splitting the two:

• 31 manifest.toml files in this repository, all requesting config_read, none declaring config_schema. Every one needs the schema before it can be discovered by a host carrying the enforcement.
• 12 distinct package names published in registry.json, across 24 entries: bluesky, gitea, matrix, mattermost, mochat, notion, redact-text, reddit, telegram, twitter, wechat, wecom.

Registry entries are immutable, so the published set cannot be fixed by editing existing entries. Each of those 12 needs a new version published with the schema in its signed manifest. The remaining 19 source-only packages just need the manifest change before they are ever published.

Practical consequence for sequencing: an operator on an old host keeps installing the old immutable entries unchanged, and an operator on a host with the enforcement needs the new versions to exist. That argues for publishing the 12 first, in whatever order, rather than treating all 31 as one atomic batch.

[JordanTheJet]

The template migration is up: #149 (redact-text, draft). Six lessons from doing the first one that every remaining package must apply:

1. Bump the version in three files — manifest.toml, Cargo.toml, and Cargo.lock. CI runs --locked; the lockfile is the one that gets forgotten.
2. Assume a guest change is needed, and that skipping it breaks the whole tool. Once the host injects typed __config, any guest deserializing it as HashMap<String, String> (or string-parsing values) fails its entire argument parse — every call returns "invalid arguments". This is a hard break, not a degradation. Grep each plugin for HashMap<String, String>, eq_ignore_ascii_case, .split(','), parse::<.
3. Never let a config error echo a config value. Config values are secret-marked, and serde_json::Error's Display quotes the offending value into text that flows back to the model. Return a sanitized error from the deserializer so callers cannot leak. Demonstrated live on redact-text, where patterns are exactly the strings the operator wants scrubbed.
4. Keep guest-side normalization even where the schema duplicates it. redact-text's empty-pattern filter looked like tidiness; removing it turns one empty pattern into a rewrite of the entire input (empty string matches at every boundary). A naive "swap string-split for typed array" migration that drops such filters ships a corruption bug.
5. Decide required per key, deliberately. All-optional means a withheld grant validates {} and the plugin runs on defaults — right for redact-text. Credential-bearing channel plugins (slack, telegram, matrix, …) should mark tokens required so they fail closed instead of starting half-configured.
6. Do not add deny_unknown_fields guest-side. additionalProperties = false already rejects undeclared keys before the guest runs; guest strictness only breaks forward-compatible schema additions.

Two repo-level follow-ups surfaced by the template work, for maintainer consideration:

• Nothing checks that a manifest's config_schema property names match the keys the guest actually reads; that drift is silent and would affect all 31 packages. The right home is one check in tools/ci/, not a per-plugin dev-dependency.
• Signed packages among the 30 must re-sign after adding config_schema (it is signature-covered). redact-text is unsigned, so feat(redact-text): declare config_schema and consume typed __config (template for #147) #149 does not demonstrate that step.

[JordanTheJet]

Correction: the operator re-key step in this checklist is tool-only

The checklist above tells every package author that operators will run zeroclaw plugin info <package>, read a zpi1_… key, and re-key their [[plugins.entries]] block. That is true for tool packages and false for channel-only packages. Correcting it here so nobody publishes a "migrated" channel release that operators cannot actually configure.

What the host actually does

installed_plugin_config_entries in src/main.rs (zeroclaw-labs/zeroclaw#9126) returns no entry unless the manifest declares both config_schema and the tool capability. That one function backs both zeroclaw plugin info <package> and install-time entry seeding. So for a channel-only package:

• zeroclaw plugin info <package> prints no config entry key.
• A fresh install seeds no [[plugins.entries]] block.
• The install path deliberately refuses to fall back to a package-name binding. A channel instance's key is zpi1(package, channel, alias), derived from the operator's configured alias. A package-level key is not the key an alias-owned channel would later resolve, so seeding one would strand operator values under a name nothing reads.

The alias-aware production path that can derive, display, and seed the per-alias key is tracked in zeroclaw-labs/zeroclaw#8852. It does not exist yet.

Revised checklist

Tool packages: full migration is possible now.

1. Add a closed Draft 2020-12 config_schema covering exactly the keys the plugin reads.
2. Deserialize the typed __config object in the guest instead of parsing strings.
3. Rebuild and re-sign (config_schema is signature-covered).
4. Publish. Operators re-key with zeroclaw plugin info <package>, and fresh installs seed the key automatically.

Channel-only packages: do steps 1 through 3 now, but do not publish as migrated.

1. Add config_schema. This is required: the host no longer discovers a manifest that requests config_read without one.
2. Deserialize typed config in the guest.
3. Rebuild and re-sign.
4. Do not label or publish the release as migrated for the typed-config host contract, and do not tell operators there is a re-key step. There is no operator step that completes the migration: nothing can display or seed the instance key until feat(plugins): activate logical channel instances zeroclaw#8852, or its accepted successor, lands. Adding the schema restores discovery; it does not make operator config reachable.

Which packages are which

Verified by reading capabilities in each plugins/<name>/manifest.toml at head 23a5dcb:

• Tool (1 of 31): redact-text (schema already in flight in feat(redact-text): declare config_schema and consume typed __config (template for #147) #149).
• Channel-only (30 of 31): amqp, bluesky, dingtalk, discord, email, gitea, gmail_push, irc, lark, line, linq, matrix, mattermost, mochat, mqtt, nextcloud, nostr, notion, qq, reddit, slack, telegram, twitch, twitter, wati, webhook, wechat, wecom, wecom-ws, whatsapp.

No package declares more than one capability, so there is no mixed case. All 31 request config_read; only redact-text currently declares config_schema.