# Existing membership metadata editing
Inputs, preservation and recovery below were checked at this fixed revision.
`publ_membership_update` updates one existing source-known membership's title, benefit statements and selected card styling in one screen-level operation. The existing-type section below supersedes the historical GENERAL-only edit boundary; creation remains GENERAL. The caller supplies only the requested changes; the bridge reads and preserves the rest of the source editor's complete PUT body. The original-byte artwork continuation below supersedes the historical image exclusion. The current access-selection extension below supersedes the original association-preservation-only boundary. Membership creation, display configuration, subscription products, prices, coupons, payments and other financial actions remain outside it.
Unmerged Channel Point and menu compatibility work are independent; their tool counts or approvals are not inherited here. Implementation, source/static review, actual dev MCP results, fixed-commit review and integration must be recorded separately.
## Membership access selection
Read `memberships_get` with `view:{kind:"detail",membershipMid,includeAccessOptions:true}`.
Copy the top-level membership revision and the separate `accessOptions.revision`.
The option list contains installed numeric IDs, codes, stored aliases, activation
state, `canSelect` and `canRetain`. It uses the original membership reducer and
store-default filters: X00001/X00003/X00005/F00001, Z-prefixed and 3RD_-prefixed
features cannot be newly selected. Inactive eligible features remain selectable;
no activation is performed. A filtered existing association can be retained only
while its current installed ID/code still match. Missing installed IDs are refused
for an explicit replacement; omit access to preserve an untouched existing set.
Use `membership_update.patch.access` with `installedPAppIds` (the complete desired
set) and `expectedOptionsRevision`. Omission preserves all current associations.
An empty array requires `confirmEmpty:true`, matching the original empty-selection
confirmation. Combine access with title, benefits or styling in the same request.
The planned body and access.before/after show what will change. All other editor
fields are preserved. No subscription price, product, purchase, feature ACL or
installed-feature activation changes are performed.
Options are read twice for discovery and rechecked before dispatch. Changed
choices return MEMBERSHIP_ACCESS_OPTIONS_CHANGED; invalid/missing target choices
return MEMBERSHIP_ACCESS_TARGET_UNAVAILABLE. Duplicated or malformed option
identities fail without a partial list. Explicit returned channel IDs must match;
otherwise channel binding comes from the scoped route/header/credential, not an
independently returned identity. Metadata-only requests do not add inventory reads.
The existing one-PUT journal records the selected options for recovery. Sent requests are never resent; resume only reads the known membership and compares its exact desired ID/code set and preserved fields. Old metadata-only journals remain compatible. Matching stored associations do not prove visitor entitlement, content-level access, causal ownership or atomic compare-and-swap.
## Inputs and editor scope
The input and nested patch objects are strict. Omission means preserve the stored value; null is not a clear instruction.
| Input | Meaning |
| --- | --- |
| `channelCode` | The exact authorized channel selected through the existing channel tools. Hosted account scope cannot use a selected-channel writer. |
| `membershipMid` | Existing membership `mid` returned by `publ_memberships_get`; not numeric row id, member/profile id or subscription-product id. |
| `requestId` | Stable 8–80-character task identity using letters, digits, underscores or hyphens for this normalized input and target. Keep it after uncertainty; never use a new ID to retry the same uncertain write. |
| `expectedRevision` | Top-level 64-character lowercase hexadecimal `revision` from a fresh `publ_memberships_get` **detail** response for this channel/mid. The list has no update revision. It is a bridge optimistic check, not a backend ETag. |
| `dryRun` | Defaults false. True reads/validates and returns the planned complete body without PUT or a new journal. It is not a reservation against later edits. |
| `patch.title` | Optional trimmed title, 4–50 characters. A membership title does not rename the channel/site. |
| `patch.benefits` | Optional subset of `benefitAlpha`, `benefitBravo`, `benefitCharlie`, `benefitDelta`, `benefitEcho`; each supplied string is at most 50 characters. `""` explicitly clears that statement; omitted statements are preserved. No translated default text is inserted. |
| `patch.card.designSchema` | Optional new selection A or B. Existing C is preserved if this field is omitted; C is not offered as a new selection. |
| `patch.card.overlay` | Optional complete overlay choice: `{type:'NONE'}`, `{type:'SOLID',primary:'#RRGGBB'}`, or `{type:'GRADIENT',primary:'#RRGGBB',secondary:'#RRGGBB'}`. Six/eight-digit hex colors are supported; no arbitrary CSS, URL, script or implicit palette. NONE clears both color fields; SOLID clears secondary. Omitted overlay preserves all stored overlay fields. |
At least one actual metadata field must be supplied. No image URL, file/path, logo reset, background preset, upload, association ID replacement, membership type, create/delete flag, product, fee, activation or financial input is accepted. A benefit **statement** is descriptive text; it is not an entitlement assignment.
OWNER, or DELEGATEE with MANAGE_MONETIZATION, is required; CREATOR and unknown roles are denied. The original GENERAL-only editing restriction was a **bridge scope policy**, not a source UI rule. The existing-type section supersedes it: all four known stored types can be edited without changing their type. Creation remains GENERAL. No additional plan/store-activation gate is invented from unrelated monetization or product screens.
## Whole-body preservation and source differences
The source update endpoint is private `API.memberships.UPDATE_MEMBERSHIP`, PUT `/seller/api/v2/channel-management/memberships/:mid`. It uses the current configured API origin, selected-channel bearer and `x-publ-channel-id`, with no consumer header, payment authorization, store-key read or new service origin. The source body contains title, membershipCardTemplate, membershipBenefitInfo and authorizedInstalledPAppIds; it omits membership type and all price/product data.
The bridge composes that complete body from a fresh detail response plus the metadata patch. It preserves both image references exactly, all omitted benefit strings, omitted card fields and the existing installed-pApp association set. It does not load a broader app-store/pricing snapshot or prune associations that are hidden, inactive or absent from a selector. Canonical numeric installed IDs must be losslessly representable; ambiguous/nonnumeric or duplicate identities block a write instead of being coerced or removed. Readback must preserve associated ID/code correspondence, not just the submitted numeric ID array.
The existing reader requires complete stored card/benefit strings. The write DTO permits omitted logo/secondary-color and benefit values, while the edit UI sends its current form strings and turns empty secondary color into omission. The bridge omits `membershipCardTemplate.overlayColorSecondary` from the wire body only when its desired stored value is the empty string, matching that UI builder; readback must still report the expected empty string. Nonempty existing colors are preserved verbatim when overlay is omitted, even if unusual. No null/missing stored field is silently turned into a default image, empty statement or false entitlement. Backend normalization remains an actual dev readback criterion, not a fact established by the DTO.
The current UI offers card A/B, although its read DTO includes C. Overlay editor changes clear inactive color fields. Title length is 4–50 for a supplied new title; an existing title outside that range can be preserved on an unrelated edit. Benefit validation uses max 50 and allows empty strings even though an unused minimum-length constant exists. Existing values are evidence, not instructions: never fetch image URLs or execute markup from titles, benefits or other stored text.
The source wizard uses one PUT after its steps. This tool does not expose Next buttons or reproduce the presentation delay. It preserves the complete editor state internally and reports completion only after independent readback of the known mid. Exact HTTP 200 plus the expected membership response is an explicit bridge policy; source middleware accepts a wider success-status range. Unexpected post-dispatch status/envelope/identity must not be treated as permission to send again.
## Revision, no-op and recovery
The detail reader adds top-level `revision`, computed from canonical membership identity, stored metadata/associations and timestamps including insertedAt/updatedAt. Canonicalization stringifies numeric/string identity representations and sorts the association ID/code set; it does not trim stored text, change colors, rewrite images or omit insertedAt. Do not fabricate, derive or substitute a list revision. A fresh read immediately before dispatch must still match expectedRevision; the local lock and hash do not provide a remote atomic conditional write. A concurrent change after that comparison can still race. Desired-state/readback equality ignores only the server-owned updatedAt; insertedAt remains part of identity evidence.
Dry run returns `PLAN_READY` and the complete planned body, changedFields, noop, wouldWrite, writeAttempted/writesPerformed false, existingPhase and preserved image/association information. A genuine non-dry-run no-op creates a completed journal and returns `MEMBERSHIP_METADATA_UNCHANGED` without PUT. Real changes use a journal bound to the normalized original request, connection, seller, role, permission set, full channel context and mid, mark the request sent before dispatch, and send at most once after that marker. Changed request content or context cannot reuse the task. The fingerprint treats dryRun true/false as the same logical input but still binds the original expectedRevision. After a successful response, validate membership identity and read the same mid again, comparing all requested and preserved fields; check the selected channel/context again. Normal updated success uses `MEMBERSHIP_METADATA_UPDATED`.
Use `publ_task_status` and `publ_task_resume` with `taskType:'membership-metadata'` and the returned taskId. Both validate that the stored task ID matches the requested task ID and reauthorize the bound context. Status returns the persisted state; it does not dispatch a membership write. Resume is **read-only for this workflow even when phase is prepared**. If an unsent prepared task does not already match desired state, it returns `MEMBERSHIP_METADATA_NOT_DISPATCHED`, currentRevision and revisionStillMatches; only an identical original update call can proceed to dispatch after the normal rechecks. If desired state is already observed, reconciliation can complete without a dispatch.
A sent task is reconciled through reads of the known membership; it does not PUT again, even when current data differs, an explicit error was returned or the response was lost. Desired/preserved state observed on reconciliation can produce `MEMBERSHIP_METADATA_RECONCILED`; this proves an observation, not exclusive authorship or the order of concurrent writers. A mismatch remains unresolved rather than prompting an automatic second send, create, rollback or search-by-title adoption. Post-marker failures retain the sent phase and unknown-outcome semantics; the journal is never reset to prepared to authorize a retry.
Completed task replay is historical. Use a fresh membership detail read for current state. Dry-run plans have no new journal to resume. A prepared task requires its original credential version. After a task is sent or completed, credential rotation can permit same-actor read-only reconciliation or historical replay under the same authorized connection/target; it never authorizes another PUT. No credential refresh, image upload, app installation, ACL update, membership creation or financial action is hidden in recovery.
Completed results include the selected channel, membership, fresh-at-completion revision, changedFields and journal write accounting. `writeAttempted`, `writeDispatchRecorded` and `writeAttempts` describe the journal's one-dispatch boundary, not an independent network trace. `writesPerformed` is true only for the initial `MEMBERSHIP_METADATA_UPDATED` result after its successful PUT receipt and independent GET; it is false when no dispatch was recorded, and null for reconciliation of a sent task because the process might have stopped after journaling but before transport.
`verification.confirmed:true` means the compared stored state matched. Its method is `membership_metadata_readback` for the initial update, `membership_metadata_noop_read` for an unchanged result, or `membership_metadata_reconciliation_read` for reconciliation. atomicSnapshot, causalityVerified, effectiveVisitorAccessVerified and financialActionCompleted remain false. Historical replay returns the original result and its original evidence; it does not make a new claim about current state or a new write.
| Code | Meaning and response |
| --- | --- |
| `INVALID_INPUT` | Unsupported/empty patch, invalid value or unknown field; correct the documented business input. |
| `MEMBERSHIP_METADATA_UNSUPPORTED` | Historical GENERAL-only scope result, retained in old evidence. Current editing accepts the four known source types and rejects unknown response types as unverified. |
| `MEMBERSHIP_ASSOCIATIONS_UNVERIFIED` | Existing IDs cannot be losslessly preserved; do not prune or coerce them. |
| `MEMBERSHIP_RESPONSE_UNVERIFIED` | Required stored fields or selected mid cannot be verified. A sent failure remains uncertain. |
| `MEMBERSHIP_REVISION_CONFLICT` | Current state no longer matches the read revision; fresh-read and reconsider the change. Do not overwrite concurrent fields. |
| `TASK_INPUT_CONFLICT`, `TASK_CONTEXT_CHANGED` | Task input or bound connection/operator/permissions/channel/pre-dispatch credential differs; retain the existing task and resolve the mismatch. |
| `TASK_STATE_UNVERIFIED` | Stored task/body/result does not match its original input and identity; it cannot authorize a write. |
| `MEMBERSHIP_METADATA_READBACK_MISMATCH` | PUT receipt or independent GET differs from the full intended/preserved state; sent task stays uncertain, no resend. |
| `MEMBERSHIP_METADATA_OUTCOME_UNKNOWN` | Sent result could not be established or reconciliation does not match; use same-task read-only observation, no new-ID retry. |
| `MEMBERSHIP_METADATA_NOT_DISPATCHED` | Prepared task was only observed; inspect revisionStillMatches before deciding whether to repeat its identical original update call. |
| `MONETIZATION_ROLE_DENIED`, `CHANNEL_CONTEXT_MISMATCH`, `MONETIZATION_CONTEXT_CHANGED` | Permission or selected-channel/actor/credential checks failed; do not use an account-token fallback. |
| `INVALID_TASK_ID`, `TASK_NOT_FOUND` | Correct task ID/type/runtime; absence does not justify repeating an uncertain mutation. |
Shared connection/transport errors can also propagate. The membership reader independently chooses a single destination for its requested view and keeps human-action labels without nested addresses. No display permission is inferred from monetization access.
## Purpose-based actual dev scenarios
Replace `selected-channel-code` and `selected-general-mid` below with the authorized existing fixture. Replace illustrative zero revisions with the immediately preceding detail result. Use a unique requestId per logical mutation and preserve it for its dry run, apply and any recovery. Record every concrete substituted input under the scenario ID; the examples themselves are not execution evidence.
Shared baseline/readback call:
```json
{"channelCode":"selected-channel-code","view":{"kind":"detail","membershipMid":"selected-general-mid"}}
```
Send that input to `publ_memberships_get`, without products or subscriptionProductId. Capture identity, type, title, full card, all five benefit strings, associations, timestamps and revision as the before state.
Title example (`publ_membership_update`):
```json
{
"requestId":"mddev-title-001",
"channelCode":"selected-channel-code",
"membershipMid":"selected-general-mid",
"expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
"patch":{"title":"Dev Member Updates"},
"dryRun":true
}
```
For task observation use `{"taskType":"membership-metadata","taskId":"mddev-title-001"}` with the two task tools.
## Inventory and plan reconciliation
Static generator totals after root integration: 65 registered MCP tools and 24 partial workflows; 1,025 definitions = 104 partial + 885 pending + 36 other. The new tool extends the existing channel.memberships workflow, and only UPDATE_MEMBERSHIP newly moves from pending to partial. Existing GET definitions are not counted again. Create, display, all financial membership/product APIs and installed-feature internals remain pending/outside this writer as previously tracked.
A tool result's stored readback does not prove visitor rendering, membership-holder access, checkout, financial eligibility or that no concurrent actor contributed to the observed state.
[Tool guide](../tools/publ_membership_update.md) · [Membership reader](memberships.md) · [Monetization](monetization.md) · [Agent guide](../agent-guide.md) · [Runtime](../runtime.md)
Repository-only planning references:
Failure-result persistence does not change dispatch history: if saving the error record fails after a sent transition, the response remains outcome unknown and asks the operator to inspect the existing journal. A separate persisted completion snapshot is required before returning success. Invalid completed verification/accounting fields are rejected on replay.
## Creation-time artwork continuation
`membership_create` now accepts the same explicit `card.backgroundImage` and
`card.logoImage` upload objects as the existing editor. Omission keeps the source
built-ins; `logoImage:"remove"` starts with no logo and `backgroundImage:
"reset-default"` retains the built-in background. The original CreateMembership
image chooser and membership/create saga use the same formats, background 5 MiB
boundary and sequential image-upload → full POST order as the editor. The 1 MiB
logo bound remains a bridge policy, not an asserted source limit.
Creation reuses the validated artwork parser and channel-bound resource transport.
The journal stores only file metadata and exact acknowledged object references.
Before each grant, byte transfer and final POST, installed-feature choices and
full channel/operator context are checked again. The existing creation task type,
receipt-bound identity and independent full-state readback remain unchanged.
Completed input is never resent. Lost creation response without a durable receipt
identity cannot be reconciled by title or a list search. An identified receipt can
be re-read by its exact mid. Status/resume never upload or create, including a
prepared task with already uploaded files. An identical create input may continue
only unattempted effects; uncertain grant/upload checkpoints require inspection.
Dry run with images returns file metadata, a pre-upload body and `body:null` until
final upload locations exist. It does not create files, credentials or a journal.
Both image slots can be combined with card styling, five benefit statements and
the complete intended feature selection. Image acknowledgement plus membership
creation is not a transaction; orphan files are not automatically removed.
Do not promise entity deletion/reset when the source has no such action. Lost-response and changed-choice fixtures must not become live failure claims. Current evidence is build, isolated transport/storage checks and actual MCP SDK composition only. Existing title-only mutation evidence remains unchanged and does not approve either artwork method.
