Skip to main content
Concept · graph
A workspace (the App calls it a review) holds proposed Graph changes under a name, and nothing reaches the Graph until you submit it.

Use when

You add, change or delete several entities or relationships, or you review what an extraction found.

Looking for something else?

One change to one entity (card Entity). Text you write and edit as a document (card Document). Starting an extraction, which opens its own workspace (card Extraction).

​
For

A workspace is a named working set. You stage entities and relationships in it. You can change what is staged. You can check out existing entities to change or delete them. You can validate the whole set, and then you submit it. An extraction opens its own new workspace for its findings, so a person can review them before anything reaches the Graph. A workspace has one status: open, submitted, applied or closed. Changes to the workspace raise its revision number. A submit can use that number as its guard.

​
Use when

  • You create several entities or relationships together.
  • You change or delete existing entities, alone or together with new ones.
  • An extraction finished and a person must review what it found.
  • You want to stop now and continue later. Close it, and restore it by id.

​
Not this

  • One change to one entity: use penumbra graph update (card Entity).
  • Text a person reads as a document: use a document (card Document).

​
Rules

  1. workspace.1 A workspace name stands for one working set. Open the same name again to continue an open workspace. An applied workspace opens again with its staged items cleared and the entities it created checked out for update. Enforced: opening the name of a closed workspace is refused with workspace_closed, which names workspace_restore and the id. Your job: use a new name for new work, and restore a closed workspace by its id.
  2. workspace.2 Staging changes the workspace only. Capture, modify and check out leave the Graph as it was. Your job: do not tell the person that a change is saved until a submit returns applied.
  3. workspace.3 Validate before you submit. penumbra graph workspace validate applies nothing and lists diagnostics. Enforced: a submit checks the workspace again, and any error diagnostic gives the outcome rejected with nothing applied. A warning, such as duplicate_name, does not stop a submit.
  4. workspace.4 Submit the revision you reviewed. Pass it to penumbra graph workspace submit as --revision. Enforced when you ask: a different current revision is refused with workspace_review_conflict and nothing is applied. Without --revision, nothing checks which revision applies.
  5. workspace.5 A submit can commit in up to three phases. The phases are changes to existing entities and relationships, new entities and relationships, and relationships from new entities to existing ones. Each phase is one commit, but the workspace is not. The outcome is applied, partial, rejected or unknown. A workspace read shows unknown as submission: unresolved. Your job: do not assume all or nothing. When a Shape in the project has rules, the whole submit runs as one transaction instead, and a failure keeps nothing from it.
  6. workspace.6 Never read partial or unknown as a rollback. rejected means nothing was applied. Your job: resume the same workspace with the same credential that submitted it, as problem submit-partly-applied says. Another credential cannot resume it, and the workspace read shows no resume line to it.
  7. workspace.7 A workspace has size limits. Enforced: a workspace holds at most 1,000 staged items (workspace_full). One submit creates at most 1,000 entities and relationships (create_plan_too_large). One submit changes at most 100 existing entities and relationships (lifecycle_plan_too_large). One submit adds at most 100 relationships from new entities to existing ones (link_plan_too_large). Validate and submit both refuse an excess, and the workspace stays open.
  8. workspace.8 To change or delete an existing entity, check it out first with penumbra graph workspace hydrate. Use --intent delete to delete it. Enforced: if the entity changed after you checked it out, validate and submit report witness_stale for that item and apply nothing. Checking out an entity that is already checked out does not refresh it. Use penumbra graph workspace refresh (rule workspace.13).
  9. workspace.9 Only an open workspace takes new staged work. Enforced: a workspace that is closed, applied or submitted refuses staging with workspace_not_open. Restore a closed one, open an applied one by name, or resume the submission if it is submitted.
  10. workspace.10 A submit from an API key or a connected agent waits for approval under the default policy. Enforced: the result is pending with an approval URL. Rules approval.1 and approval.3 say what to do.
  11. workspace.11 Closing sets a workspace aside. The App calls this discarding a review. Enforced: penumbra graph workspace close closes only an open workspace, and any other status is refused with workspace_not_open. Nothing reaches the Graph, and no staged item is deleted. Your job: tell the person that nothing was added. Restore brings the workspace back with its items (rule workspace.12), so use a new name to start clean.
  12. workspace.12 Restore brings a closed workspace back by its id. Enforced: penumbra graph workspace restore refuses a workspace that is not closed with workspace_not_closed. Extracted entities are compared with the Graph again, so one that matches an entity added since updates that entity and makes no duplicate. An entity or relationship you pulled in that changed or was removed while the workspace was closed carries a flag. So does an item written under a Shape that has a newer version. Nothing refreshes on its own, and a submit still refuses a changed entity with witness_stale. Your job: read the flags before you submit, then refresh or remove each flagged item (rule workspace.13).
  13. workspace.13 Refresh brings one pulled-in entity up to date. Enforced: penumbra graph workspace refresh <workspace> <handle> reads the entity again at its current revision. Your change stays only on fields that did not change since you read the entity. A field that changed loses your change and is named in a refresh_conflict flag, and you set it again with penumbra graph workspace modify. An item that extraction linked to an entity is compared with the Graph again. An entity that was removed is refused with refresh_unavailable. Your job: read the conflict flag before you submit.

​
Failure signs

​
Doors

The default catalog has no call that closes or restores a workspace. Use the CLI, the SDK or the full catalog.

​
The CLI word

The CLI calls an entity a node in its workspace output.

​
HTTP reference

​
Keep going

Entity · Relationship · Approval · Extraction · Review a workspace and submit it