A View does not follow a Shape change until it is published again

​

Signs

• Every read by a credential limited to the View fails with view_republish_required and HTTP status 409.
• The CLI prints that the project’s Shapes changed since the View was published.
• Or nothing fails, and entities of a new type are missing for the client. A read of one by its ID gives not_found, though a person with full access sees it.
• The Shape changed after the View’s last publish. Run penumbra context slice show <view-id> for the time of the publish, and compare it with the Shape change.

​

Why it happens

A View keeps the entity and relationship type names it showed when you published it, and the Shape versions it was built from. The Graph filters a limited credential by type name. Files in included collections are different: Penumbra reads them when someone reads. A Shape change can make a name the View includes mean a different type, for example when a new Shape declares the same name. The filter could then show a type the View never included. Penumbra refuses every read until the View is published again. Other Shape changes do not break the View. It keeps its old list, so a new type stays hidden.

​

What Penumbra does

By itself:

• Reads the newest published version of the View when a limit follows the View, and keeps a pinned limit on its version.
• Fixes the entity and relationship type names of the View when it is published.
• Refuses every read with view_republish_required when a Shape added or changed after the publish declares a name of the View for a different type. A pinned limit gets the same refusal.
• Keeps the View working after any other Shape change, and it shows only the types it listed at its publish.
• Reads the members of an included collection when someone reads, so a File that joins a collection appears without a new publish.
• Refuses a publish with semantic_scope_ambiguous when a type name inside the View is also the name of a type outside it.

You must:

• Decide with the person whether the client should see the change, before you publish the View again.
• Publish the View again with penumbra context slice publish <view-id>, as a person who may change Views.
• Attach the new version again with penumbra access attach when a limit is pinned, because a new publish does not change a pinned limit.
• Rename one of the types in its Shape when the publish is refused with semantic_scope_ambiguous. Expect this refusal when the View does not select the changed Shape.

Not handled:

• Penumbra does not publish a View again when a Shape changes, and does not tell the View’s owner that a Shape change affects the View.
• A limited credential cannot publish the View, so the client and their agents cannot fix it.
• The CLI hint for view_republish_required says to publish again. It does not mention that the publish can be refused with semantic_scope_ambiguous.
• A publish of a draft that did not change is refused with context_version_conflict, and its hint says to read the View again and retry.

​

Do

1. Confirm the limit. Run penumbra access me with the limited credential. It names the View and its version. As a manager, penumbra access list shows each limit and whether it follows the View or is pinned.
2. Tell the person that the View needs a new publish, and who can do it. An editor, or a key with context.view.write, can publish. A client cannot.
3. Ask whether the client should see the Shape change. A new publish also shows every other change made to the View’s draft (card rule view.1).
4. Read the draft: penumbra context slice show <view-id>.
5. Save the draft again with no change. Run penumbra context slice update <view-id> --purpose "<purpose>" with every --collection-id and --shape-id it has. A publish of a draft that did not change is refused with context_version_conflict.
6. Publish it: penumbra context slice publish <view-id>. A key or agent waits for approval (problem change-waits-for-approval).
7. Expect a refusal when the View does not select the changed Shape. The publish is then refused with semantic_scope_ambiguous until the names differ. Read the labels in the message. Rename one type of each pair in its Shape (recipe change-a-shape), or choose different Shapes and types for the View. Then publish again.
8. For a limit pinned to a version, attach the new version: penumbra access attach <view-id> --member <subject-id> --version <number>. Use --credential <credential-id> or --connection <connection-id> for a key or an agent. penumbra access list shows which limits are pinned.
9. Get the version ids with penumbra context slice versions <view-id>. Then compare two versions with penumbra context diff versions <left-version-id> <right-version-id>. It lists the Shape versions and entity types that changed.

​

Don’t

• Don’t remove the limit with penumbra access remove to make reads work. The key, agent or login then reads the whole project.
• Don’t change the Shape back only to quiet the refusal, unless the person wants that change undone. The Shape change was a decision of its own.
• Don’t tell the client that their entities were deleted. They are hidden from the View, and a person with full access still sees them.
• Don’t publish the View again before you read the draft. The publish also makes your latest edits visible.

​

Check

• penumbra access me run with the limited credential names the new version of the View.
• A read that failed with view_republish_required now works.
• penumbra context slice version <view-id> <number> lists the new type under “entity types”, and the client can read an entity of that type.

​

Related

Card view, with rules view.1, view.3 and view.12. Card credential. Problem hidden-reads-as-missing. Recipe share-with-a-view.

​

Keep going

View · Brain · Credential · Something outside the View reads as not found · Share part of a project with a View · Change a Shape and publish it · Shape