Review a workspace and submit it

​

Outcome

The workspace has status applied, and each entity and relationship it held is in the Graph. If that is not yet true, the person knows what waits, who must act, and why.

​

Before you start

1. Name the workspace and read it: penumbra graph workspace show "<name>". The first line shows its status and revision. It must show open. If it shows submitted, go to problem submit-partly-applied (rule workspace.9). If it says items: none of 0 here, stage items first.
2. Know your credential: penumbra whoami. An API key or a connected agent waits for approval at the submit (rules approval.1 and approval.2). A person’s own session does not.
3. Plan to use one credential for the whole recipe. Only the credential that submits can resume a partial submit (rule workspace.6).
4. Choose a request id for the submit, such as --request-id submit-<name>-1. You need it to recover a lost reply (problem reply-lost).

​

Steps

1. Read the workspace and note its revision.
   • CLI: penumbra graph workspace show "<name>".
   • MCP: review_work with the workspace id (default catalog), or workspace_read (full catalog and Kits).
   • Expect: a list of items with handles, then submission: not started and submit with --revision <n>.
2. Review every item against its source. An item that says updates existing came from an extraction. It changes the entity it names, and the submit makes a new revision of that entity. Check that it is the same thing. If it is not, run penumbra graph workspace keep-new "<name>" <handle> (problem extraction-duplicates-existing-entity). If you must correct an item, edit it with penumbra graph workspace modify "<name>" <file>. An item for an entity that exists takes a patch, and the patch keeps the properties you leave out (rule entity.2). An item that is new in this workspace has no earlier properties. An edit of its properties replaces the whole map, so send every property you want to keep. Then read the workspace again, because each edit changes the revision (card workspace).
3. Check the whole workspace.
   • CLI: penumbra graph workspace validate "<name>".
   • MCP: workspace_validate, or penumbra.workspace(reference).validate() inside execute.
   • Expect: valid: yes, a review: line, a line would apply: with counts, and a next: line. With no review flags it is next: penumbra graph workspace submit "<name>" --revision <n>. If items carry review flags, it is next: penumbra graph workspace show "<name>": read the flagged items, then take the revision from show. A line N extracted items update a record the project already has can follow. Fix every line that starts with error and validate again (rule workspace.3). Tell the person about each warning.
4. If the would apply: line shows deletions, tell the person which entities it deletes before you go on. A delete removes the entity’s relationships too (rule entity.3).
5. Submit the revision that validate or show printed.
   • CLI: penumbra graph workspace submit "<name>" --revision <n> --request-id <key>.
   • MCP: workspace_submit with expected_revision (full catalog and Kits at confirm or apply), or penumbra.workspace(reference).submitReviewed with expectedRevision inside execute (default catalog).
   • Expect: submission: applied, a counts line, one line for each created, updated or deleted entity (add --detail to list relationships too), and exit code 0. See rules workspace.4 and workspace.5.
6. If the CLI exits with code 4 and prints outcome: pending, the change waits for approval. Give the person the approval URL and tell them that nothing has changed yet. Then follow it: penumbra operations wait <handle> (rules approval.3 and approval.4). In the default catalog, use check_status with the approval reference.
7. When the wait ends, read the workspace again with step 1 and go to Check.

​

Check

1. Run penumbra graph workspace show "<name>". The first line must show [applied <id>], and the line submission: must read applied.
2. Run penumbra graph get <id> for two of the ids that the submit printed. Each must show the type you staged and a revision.
3. If the check fails, do not submit again. Use the table below.

​

If it goes wrong

​

Worth offering

• If the submit waits for approval, offer the owner a short list of what it changes, one line for each change.
• Offer to check what else the applied change touches (reference how-penumbra-fits-together).

​

Report

Tell the person:

• The outcome: applied, waiting for approval, partly applied, or rejected.
• How many entities and relationships were created, changed or deleted, by type.
• What still waits, who must approve it, and the approval URL.
• Each warning that validate gave, and what you did about it.
• The request id of the submit.

​

Keep going

Workspace · Approval · Entity · A change returned pending · A submit is partly applied or unresolved · The workspace changed since you read it · The reply to a change was lost · A Graph write returned graph_write_busy