microvoid · fearclear · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
@@ -321,7 +321,7 @@ bun run check               # complete fail-closed local CI sequence
 ```
 
 Marketplace publication consumes the public authoring contracts
-`@convax/plugin-api@1.0.0`, `@convax/plugin-sdk@0.1.0`, and
+`@convax/plugin-api@2.0.0`, `@convax/plugin-sdk@0.1.0`, and
 `@convax/marketplace-kit@0.2.0`. Local source links are validation aids, not valid
 publication dependencies. All three exact packages must be available from the
 configured registry before a clean frozen install or publication can succeed.

@@ -244,7 +244,7 @@ bun run check               # 执行完整 fail-closed 本地 CI
 ```
 
 Marketplace 发布消费公开 authoring contract：
-`@convax/plugin-api@1.0.0`、`@convax/plugin-sdk@0.1.0` 与
+`@convax/plugin-api@2.0.0`、`@convax/plugin-sdk@0.1.0` 与
 `@convax/marketplace-kit@0.2.0`。本地源码 link 只用于验证，不是有效的发布依赖；
 三个精确版本都必须先在配置的 registry 可用，干净 frozen install 与发布才可成功。
 参见 [SDK authoring rollout blocker](docs/sdk-authoring-contract-rollout.md)。

@@ -24,7 +24,7 @@ have.
 
 ## Catalog evidence
 
-- Checked Catalog version: `@convax/plugin-api@1.0.0`, canonical JSON SHA-256 `5647290670309c550c144b2746a17bc0fa0dd504484fb137952620896dc889e4`.
+- Checked Catalog version: `@convax/plugin-api@2.0.0`, canonical JSON SHA-256 `a23b847c3513e810777a0444ee3c3cd20414b4ee57e2b93a0a663fba2545e99d`.
 - Closest existing APIs: `@convax/plugin-sdk/client` exports the normal Web Plugin client; the Host API Catalog contains no Pet-surface transport factory because Pet operations are contribution-scoped rather than ordinary `hostApi` calls.
 - Availability result: the installed public SDK has no SDK-owned Pet overlay/settings client, connection parser, typed request/result parser, cancellation contract, or late-response policy.
 - Why required/optional declaration does not solve it: `hostApi` negotiation cannot change a `contributes.pet` surface into a normal Web `entry` or manufacture a missing SDK transport owner.

@@ -31,7 +31,7 @@ Status: pending human review
 
 ## Catalog evidence
 
-- Checked Catalog version: `@convax/plugin-api@1.0.0`, canonical JSON SHA-256 `5647290670309c550c144b2746a17bc0fa0dd504484fb137952620896dc889e4`.
+- Checked Catalog version: `@convax/plugin-api@2.0.0`, canonical JSON SHA-256 `a23b847c3513e810777a0444ee3c3cd20414b4ee57e2b93a0a663fba2545e99d`.
 - Closest existing APIs: none; this is an authoring, Registry, installation, and
   companion-launch contract rather than a Web or Agent callable API.
 - Availability result: the current contracts admit one verified primary

@@ -0,0 +1,140 @@
+# Host capability request: Web Plugin generation input binding
+
+Status: pending human review
+
+## User problem
+
+- Affected Plugins and source versions: `jianying-editor@3.0.0`,
+  `multi-angle@0.2.0`, and `relight-studio@0.2.0`.
+- Checked Catalog: `@convax/plugin-api@2.0.0`, schema
+  `convax.plugin-api-catalog/3`.
+- Released-authority mismatch: `canvas.inputs.list` deliberately returns only an
+  opaque `inputKey`, while the prior generation contract required a `nodeId`.
+  Treating the opaque key as a Canvas node id was an invalid hidden assumption.
+- The local API 2 development Catalog corrects that shape, but it is not
+  publication authority until the protected receipt binds the exact contract.
+
+## Blocked Plugin use case
+
+- A Web Plugin selects one directly connected image through
+  `canvas.inputs.list`, previews it through the separately governed image
+  session APIs, and then submits that exact input as a generation reference.
+- The Plugin must not learn or reconstruct a Canvas node id, native path, resource
+  hash, or Host implementation detail.
+- Edge, resource, revision, caller, cancellation, and stale-scope checks remain
+  Host-owned immediately before the external generation call.
+
+## Catalog evidence
+
+- Checked Catalog version: `@convax/plugin-api@2.0.0`, canonical JSON SHA-256
+  `a23b847c3513e810777a0444ee3c3cd20414b4ee57e2b93a0a663fba2545e99d`.
+- Closest existing APIs: `canvas.inputs.list`, `canvas.inputs.image.open`, and
+  `generation.execute`; `canvas.inputs.list` returns pathless descriptors keyed
+  by `inputKey`.
+- Availability result: the mechanically vendored API 2 candidate accepts
+  `references: [{ inputKey, role }]`, with `since: 1.0.0`,
+  `contractSince: 2.0.0`, and contract digest
+  `sha256:a7ec11a6894247ae4485414a82a8a409f618d00bf3206e973ab111d4e7fa8247`.
+- Why required/optional declaration does not solve it: declaring
+  `generation.execute` negotiates only an already-published contract; it cannot
+  approve candidate bytes or let `canvas.inputs.image.open` bearer possession
+  grant generation authority.
+- `acceptedApiContracts` binds the exact generated candidate digest while the
+  request and all affected versions remain pending. Local bytes do not approve
+  the contract or replace the protected Host release and human decision receipt.
+
+## Requested generic contract
+
+- Proposed capability id or contribution: correct the API 2
+  `convax.plugin-api-wire-schema/3` `generation.execute.references[]` item to
+  `{ "inputKey": "<opaque direct-input key>", "role": "<declared role>" }`;
+  keep `generation.execute` as the API id because this is a breaking correction
+  within the unpublished API 2 cutover, not a Plugin-specific method.
+- Intended audiences: `web-plugin`.
+- Scope: the exact installed Plugin principal and owning Canvas node connection.
+- Side effect: unchanged `execute`.
+- Required grant: unchanged `generation.execute`; image-preview grants do not
+  imply it.
+- Bounded request: accept at most the Catalog-defined number of unique
+  `{ inputKey, role }` references plus the existing bounded prompt, output,
+  result mode, and tool id; reject `nodeId`, paths, URLs, session ids, unknown
+  fields, unrelated keys, duplicate bindings, and unsupported roles.
+- Bounded response: retain the existing bounded generation result and never
+  return the resolved Canvas node identity, native path, or staged resource.
+- Stable errors: retain the published generation errors and use
+  `stale-context`, `permission-denied`, and `resource-unavailable` for invalidated
+  authority or resources without exposing private diagnostics.
+- Cancellation and stale-scope behavior: resolve each key only against the
+  caller's current direct incoming inputs, bind caller and resource revisions,
+  propagate cancellation, and revalidate the exact edge and resource immediately
+  before execution; cancellation or staleness before the billable boundary
+  prevents execution.
+
+## Alternatives considered
+
+- Expose `nodeId` from `canvas.inputs.list`: rejected because it widens a
+  pathless capability into Canvas structure disclosure and encourages callers to
+  retain stale authority-shaped identifiers.
+- Add an `inputKey -> nodeId` mapping API: rejected because it creates a reusable
+  identity leak and a confused-deputy surface with no Plugin need.
+- Reuse the image bearer URL or session id: rejected because preview possession
+  is not generation consent and the session is revoked promptly after decode.
+- Omit references and infer an arbitrary connection: rejected because multiple
+  direct inputs require an explicit, stable caller selection.
+
+## Security and authority
+
+- Bind every key to the caller snapshot, frame, Project, Canvas, owning node,
+  direct edge, source resource identity, and current media revision.
+- Reject caller-supplied node ids, paths, URLs, session ids, unrelated keys,
+  duplicate bindings, unsupported roles, stale edges, and changed resources.
+- Revalidate after asynchronous preparation and immediately before a billable
+  call. Cancellation before that boundary must prevent execution.
+- The callee receives only the Host-staged resource permitted by the selected
+  generation tool contract; no identifier or native path crosses renderer IPC.
+
+## Compatibility
+
+- API major 1 packages remain unsupported by the API 2 flag day and are not
+  reinterpreted.
+- API 2 packages using the corrected reference shape remain publication-blocked
+  until the generated Catalog, SDK parser/client, runtime conformance evidence,
+  and protected external decision receipt agree on one exact digest.
+- Rollback removes the new Plugin versions; it never treats an opaque key as a
+  node id or falls back to private IPC.
+
+## Falsifiable acceptance tests
+
+1. Generated Catalog and SDK accept only `{ inputKey, role }` for
+   `generation.execute.references[]` and reject `nodeId`.
+2. A current opaque key for one direct incoming image reaches the existing
+   generation executor without exposing its resolved Canvas identity.
+3. Wrong Plugin/frame/Project/Canvas/node, unrelated or malformed key, removed or
+   replaced edge, changed media revision, duplicate reference, and unsupported
+   role fail before external execution.
+4. Cancellation and stale scope after preparation but before the billable
+   boundary produce no external call and no Canvas mutation.
+5. Preview-session possession alone cannot authorize generation, and closing the
+   preview session neither invalidates nor broadens the separately revalidated
+   generation request.
+6. Jianying Editor, Multi Angle, and Relight Studio packed assets contain no
+   `nodeId` reference workaround and submit only opaque keys returned by their
+   current input list.
+
+## Plugin-side plan after approval
+
+- Persist only the selected opaque input key plus harmless revision/dimension
+  metadata; never persist a resolved Canvas identity or bearer URL.
+- Submit `{ inputKey, role }` through the generated SDK client and keep
+  cancellation and stale-input tests.
+- Audit any future Web generation Plugin as a separate affected identity before
+  moving it to the corrected contract.
+
+## Human decision audit record
+
+- Decision: pending
+- Reviewer identity: pending
+- Decision time: pending
+- Protected receipt URL and SHA-256: pending
+- Accepted published contract version and digest: pending
+- Runtime conformance evidence: pending