Sentinel Vault

11Sealing a file: where and how

One click on the Seal button — from the inline panel macro or the Manage Attachments overlay — writes the seal record, posts a confirmation comment, and auto-inserts the panel onto the page.

Two surfaces offer the Seal button. The first is the Sentinel Vault panel — a block macro (manifest key sentinel-vault-panel, description "Shows reservation status for every file on this page") that lists every attachment on the page as a card. The second is the full-screen Manage Attachments overlay, opened from the page ribbon's "Manage Attachments" button (the ribbon is the sentinel-vault-ribbon page banner; the overlay is a Custom UI modal opened at runtime via new Modal({ resource: "overlay" }) — deliberately not a manifest module of its own). Both call the same seal-artifact resolver, so behavior is identical.

What one click on Seal actually does (seal-artifact)

1. 1The button — labelled Seal, tooltip "Reserve this file so only you can modify it", busy state "Sealing" — sends { attachmentId } to the resolver.
2. 2The resolver refuses if a LIVE seal by another user exists: { success: false, reason: "Attachment is already sealed by another user" } shows under the card as an inline error. An EXPIRED seal by another user does not block — it is cleared, its edit requests/grants swept, and its stale space-index row dropped, then sealing proceeds (the SV-M8 re-seal path).
3. 3The hold duration is resolved through the policy chain (next section) and expiresAt is stamped.
4. 4The attachment's details are fetched as you: sealedVersion (current version number), sealedFileId, name, size, download link. The page body is read server-side to capture the presentation baseline and the tri-state embedded field.
5. 5The seal record is written to protection-{attachmentId}, the space index row to space-protection-{spaceId}-{attachmentId}, the protection- content property onto the page, and the global protections-last-modified stamp is touched.
6. 6A confirmation footer comment is posted on the page — header "Seal Active", body "you have sealed \"<file>\" on <page>. Valid until <date>. No one else can modify the file while your seal is active." — with an @mention of you, so Confluence's own notification engine emails you.
7. 7The Sentinel Vault panel macro is auto-inserted into the page body if it is not already there (triggerPanelEmbed), so the seal is visible to everyone who opens the page.

How the surfaces stay fresh

The inline panel loads in two phases: enumerate-page-seals returns the sealed cards instantly from the app's own storage (no Confluence API call), then the full attachment list is merged in from the paged enumerate-doc-artifacts read. The page ribbon polls check-seal-stamp every 5 seconds; because every seal mutation touches protections-last-modified, a seal made in the overlay shows up in the panel — and vice versa — within one poll tick.

12How long a seal holds: the duration policy chain

Space override beats global default beats the API payload beats the 48-hour baseline — and the final value is always clamped to a positive, finite span of at most 100 years.

The resolution order (sealArtifact, first match wins)

The clamp every candidate passes through (shared/baseline.js)

withinHoldBounds(raw) =
  typeof raw === "number"
  AND Number.isFinite(raw)
  AND raw > 0
  AND raw <= MAX_HOLD_SECONDS   // 100 * 365 * 24 * 60 * 60 — 100 years,
                                // safely inside the JS Date ±8.64e15 ms range

sanitizeHoldDuration(raw) = withinHoldBounds(raw) ? floor(raw) : 172800 (48 h)

The clamp runs TWICE: once on the incoming lockDuration payload (a negative value would produce a past expiresAt — a "sealed" record with zero protection returned as success; a non-numeric one would crash new Date(...).toISOString()), and once more on the FINAL value after the policy chain, because stored policy values are persisted raw and never bounds-checked at save time. A corrupt stored policy therefore degrades to the 48-hour baseline instead of producing an unprotected or crashing seal. expiresAt is then now + holdPeriod x 1000 as an ISO string on the record.

13What the seal record captures

One KVS record holds identity, timing, and — since the 2026-08 release — the revert target, the presentation baseline and the tri-state embedded field; two more legs (space index, content property) keep every surface in sync.

Fields written to protection-{attachmentId} at seal time

lockedBy / lockedByName / lockedByEmail

The sealer's account id, display name and email (best-effort from /wiki/rest/api/user/current; a failed lookup leaves "Current User" / null).

timestamp / expiresAt / lockDuration

Seal creation time (ISO), expiry time (ISO), and the resolved hold span in seconds. expiresAt drives the halfway reminder, the expiry notice, the "Overdue" badge, and every inertness check.

sealedVersion / sealedFileId

The attachment version number and internal file id AS THEY WERE at seal time. sealedVersion is the revert target for overwrites (S1); sealedFileId is how the page-body pass finds the sealed embed in the ADF. Legacy seals without sealedVersion fall back to reverting to currentVersion - 1.

spaceKey / spaceId / contentId / attachmentName / downloadLink

Location and display metadata: the space, the parent page, the file name and its download link — what listings and notifications render without re-fetching.

mediaBaseline

The presentation baseline: { layout, width, widthType, mediaWidth, mediaHeight } captured from a SERVER read of the page ADF at seal time. null when the file is not embedded or the read failed — presentation protection is simply inactive for that seal.

embedded (tri-state)

true = the sealed file was embedded in the page body at seal time; false = provably attached-but-not-embedded; ABSENT = unknown (the ADF read failed, or the seal predates the field). The distinction decides whether absence from the page is treated as tampering — see the owner-intent section.

The triad

Every seal lives in three places at once: the KVS record protection-{attachmentId} (the source of truth), the space index row space-protection-{spaceId}-{attachmentId} (what the space console lists), and the protection- content property on the parent page (the trigger fast-path probe and the CQL discoverability hook). Every mutation also touches protections-last-modified, which the 5-second frontend poll and the hourly index cron use as a change gate.

14What a seal defends against

Five tamper vectors, five responses — every one restores the sealed state without destroying the editor's work, except permanent deletion, which is answered honestly instead of pretended away.

Tamper vector → response

Why the app never fights itself

Every restorative write is made as the app (asApp()), and both triggers compare the event actor against the app's own cached account id (app-account-id) before doing anything — so the re-fire caused by the app's own restore is absorbed instead of reverted again. If that id cannot be resolved (fresh-install race, a persistent 401 on /user/current), BOTH triggers now fail CLOSED: they skip enforcement for that run rather than risk an unbounded revert loop. Briefly-unprotected beats runaway version churn.

15Presentation seals in depth

Sealing an embedded image also seals how it presents on the page — a fixed five-attribute protect-list compared between server reads, immune by construction to editor attr noise.

The design decision is STRICT: a sealed image's on-page look is part of what is sealed. But comparing whole ADF nodes would false-positive constantly — the live editor regenerates attrs like localId and occurrenceKey on every save. So the comparison covers ONLY a fixed protect-list, and everything else on the node is ignored by construction.

The protect-list (infra/media-presentation.js)

mediaSingle wrapper:  layout, width, widthType
media child:          width (mediaWidth), height (mediaHeight)

presentationDiffers(baseline, current):
  null-safe exact equality on those 5 keys only
  no baseline -> no attr protection (legacy seals: never a violation)

Baselines cancel out normalization

The baseline is captured from a SERVER read of the ADF at seal time and compared against later SERVER reads. That matters because Confluence normalizes attrs on write — a width of 50/percentage written over REST was observed coming back as 340/pixel. Capturing and comparing on the same side of that normalization means it cancels out.

Behavior on a save that changes the presentation

• Every copy of the sealed embed on the page is found and compared (findAllSealedMediaSingles) — a resized copy-paste duplicate cannot hide behind a pristine first match.
• Change by the owner or an active grantee → the seal re-baselines to the new look (the first copy is canonical) and nothing is reverted. The re-baseline merges onto a fresh read of the record, because the attachment trigger can be re-baselining sealedVersion for the same save concurrently.
• Change by anyone else → applyPresentation restores the baseline attrs onto every differing copy inside the same page write, and a layout-changed notification is queued: the footer comment reads "attempted to change the presentation of … The sealed presentation has been restored."
• A grantee replacing the binary itself gets a fresh baseline captured against the NEW file id — the old image's dimensions must not be "restored" onto the new image. If that capture fails, the seal keeps NO baseline: attr protection off beats reverting to a stale look.

16Owner intent: your own destructive actions release the seal

A seal protects the owner's content FROM OTHERS — so an owner trashing their own sealed file, or removing their own embed, is recorded as sanctioned rather than reverted.

The failure this design closes: an owner deliberately trashes their own sealed file, the live seal remains, and the NEXT unrelated page save by a bystander triggers the trash-restore path — un-deleting the owner's file and posting a violation comment that publicly blames someone who did nothing. Owner intent is therefore captured at the moment of the action, on both the event path and the UI path (either can race or drop).

Owner (or grantee) destructive actions and what they now mean

The tri-state embedded field, spelled out

embedded: true

Proven embedded at seal time. Absence from the page body IS tamper evidence: the lookback restore runs, and if it exhausts all 5 prior versions the owner gets an honest "could not restore" notice.

embedded: false

Provably attached-but-not-embedded (at seal time, or re-baselined by an owner/grantee removal). Absence is the file's NORMAL state — never a violation, never a restore.

field absent

Unknown — a legacy seal or a failed ADF read at seal time. The lookback still runs, but on exhaustion the app skips SILENTLY: without proof the file was ever embedded, a public "was modified" comment would be a false accusation of whoever happened to edit the page.

17How page-body restoration actually works

One read, ordered in-memory passes, one write inside a 409 backoff loop — with the attachment layer unified so a node is never re-spliced while its file sits in trash, and destruction is never inferred from a single 404.

The pipeline on every page save (pageContentTrigger)

1. 1Cheap probes first: does the page carry a protection- or section-protection- content property? Unrelated pages cost ~2 property GETs and stop here — no page-body read.
2. 2One readDocBody produces the in-memory ADF; the section pass, then the media pass, mutate it in order.
3. 3One writeDocBody commits everything, version + 1, with the message "(Sentinel Vault restored protected content)". A 409 (someone saved concurrently) retries the WHOLE read→passes→write cycle up to 3 times with 2^n x 500 ms backoff.
4. 4Notifications are dispatched ONLY after a confirmed OK write, and only the entries from the attempt that actually wrote — a lost race never claims "restored".

Un-trash first, then re-splice

Before re-inserting a missing sealed media node, the pass probes the attachment itself: current → splice; trashed → restore the attachment from trash FIRST (shared restoreAttachmentFromTrash, the same helper the trash trigger uses — probe-first so the two racing paths are idempotent), then splice; deleted → never splice a dead node — run the permanent-delete cleanup with its honest notice instead; unknown → splice, failing toward protection. This unification exists because the old code re-inserted ADF nodes pointing at trashed files, which render nothing while the comment claimed "reverted".

The lookback accumulates

The re-splice source is not blindly "the previous version". The pass walks back up to 5 versions (MAX_LOOKBACK = 5) and ACCUMULATES: each still-missing file is restored from the most recent version that still contained it, and different files may come from different versions. Restored nodes are spliced back descending-index so earlier splices cannot shift later positions.

18Expiry: notify-only sweep, lazy release

The hourly sweep only ever notifies; expired seals become inert everywhere immediately and are physically deleted lazily, on the next read that touches them.

When expiresAt passes, nothing deletes the seal at that instant. Instead two things are true at once: the seal is INERT — every enforcement path (overwrite revert, trash restore, embed re-splice, presentation revert, section restore) checks expiresAt first and declines to act — and the record is cleaned up LAZILY the next time something reads it: computeSealStatus (behind every panel/overlay/console read) deletes the record, removes the content property and the space-index row, and fires the watcher release notices. Until that read happens, listings show the seal with an Overdue badge.

What the hourly expiry sweep does (expirySweepTask — and does NOT do)

Re-sealing over an expired seal

Because deletion is lazy, an expired-but-unswept record could otherwise block a legitimate new seal. sealArtifact treats an expired seal by another user as absent: it deletes the stale record, sweeps the previous owner's edit requests and grants (they carry no TTL of their own and would leak into the new seal as phantom entries), and drops the old space-index row when the new seal resolves to a different space — then seals fresh.

19Violation notifications and the 24-hour dedup

Every incident is recorded per occurrence, but the page gets at most ONE comment per (page, target, class) per 24 hours — re-armed early by a clean save.

A violation fans out on up to three channels. The dispatch record (feeding page banners and console timelines) fires on EVERY occurrence — the audit trail stays truthful. The toast key (violation-alert-…, 1-hour TTL) fires per occurrence when toasts are enabled. The footer comment — @mentioning both the seal owner and the editor, so Confluence's notification engine emails the owner — is the deduplicated channel, because the incident that motivated the design was a stale editor draft re-publishing every few minutes and re-posting an identical comment each time.

The dedup marker

violation-noticed-{pageId}-{targetId}-{class}   TTL 24 h

classes: content-loss | revert-failed | layout-changed
         | section-removed | section-edited

"delete" (trash handler) and "content-removal" (media pass)
BOTH alias to content-loss — a UI delete of an embedded attachment
fires trashed:attachment AND updated:page, one physical event,
and must never produce two comments.

The claim discipline (why the window is never wasted)

• The marker is claimed ONLY when the comment channel is actually postable — both ENABLE_CONFLUENCE_BULLETINS and ENABLE_NATIVE_NOTIFICATIONS on. A toggled-off channel must not burn the 24 h window with no comment to show for it.
• A claimed marker whose post then throws or reports failure is RELEASED — a transient 5xx must not consume the owner's one notice.
• A CLEAN save (no violation of any kind on that surface) clears the markers for its targets — the next genuine tamper is a new incident and comments afresh, even inside the 24 h.
• If the marker infrastructure itself errors, the app notifies anyway: a possible duplicate beats a suppressed real violation.

What each comment class actually says (notice-blueprints.js)

20Watch: get told when a seal is released

A Watch button on files sealed by someone else registers a 7-day notification request, honored on unseal and on lazy expiry.

On any card sealed by another user, the panel and overlay show Watch (tooltip "Get notified when relinquished"; already-watching state "Watching", tooltip "Stop watching" — clicking again cancels). The request is stored as notify-request-{attachmentId}-{accountId} with a 7-day TTL: a watch older than a week that never triggered simply evaporates.

When watchers are notified (notifyWatchers)

• The owner unseals, or a steward force-unseals — the release notice posts immediately.
• An expired seal is lazily released by any read (computeSealStatus) — the release notice posts then, not at the moment expiresAt passed.
• The notice is a footer comment @mentioning the watcher ("<file> is available again as of <date>") — Confluence emails them per their own notification preferences.
• A watch request is consumed ONLY when its notice actually posted; on a transient failure it is kept for a later retry, bounded by the 7-day TTL. Up to 50 watchers per artifact are processed.

21Restore, Delete, Purge: the gated actions

Three destructive/recovery actions, each behind a global admin toggle that ships OFF — and purge additionally requires owner-or-steward, always.

Status badges these actions revolve around (panel + overlay)

The three actions

The toggles are read fresh on every listing (enumerate-doc-artifacts / enumerate-page-seals return allowRestore/allowPurge/allowDelete per card), so flipping one in the admin console changes which buttons render on the next panel refresh — and the resolvers re-check server-side regardless of what the UI shows.

22The honest-failure principle

The app never claims a restore that did not land — failed enforcement is surfaced loudly, and every destructive conclusion must be proven, not observed once.

The core rule (SV-M2 in the app's own contract): no false success. A protection app that says "restored" when the tampered version is still live is worse than no protection at all, because the owner stops checking. Every enforcement path is built so that its notification is only ever dispatched after the write it describes was CONFIRMED.

Where you will see it

• A failed attachment revert (download or re-upload exhausted its 3 retries) posts the revert-failed comment — "Sentinel Vault could NOT automatically restore it…" — instead of returning silently. The tampered version stands, and the owner KNOWS it stands.
• A trash restore that fails keeps the seal in place (the file is still in trash and recoverable) and posts the same honest notice — the old behavior of deleting the seal and emailing a false "deleted" is gone.
• The page-body pipeline dispatches its "reverted" notifications only after the single PUT returned OK; if every 409 retry lost, nothing is claimed — and only the notifications computed by the attempt that actually wrote are sent, never a stale earlier attempt's.
• When the 5-version lookback cannot find a sealed embed that was PROVEN embedded, the owner gets a loud "could not restore" notice instead of the old silent skip; when the seal carries no embed evidence, the app stays silent rather than publicly accusing an innocent editor.
• Even unseal double-checks itself: after deleting the record it re-reads the key, and answers "Seal removal could not be confirmed" rather than reporting a release it cannot verify.
• Permanent deletion is reported as exactly that: "It cannot be restored — the file is permanently gone and the seal has been released." No fake recovery path is offered.

23What a sealed section is

A sealed section is a slice of a page wrapped in the app's bodied macro, snapshotted at seal time, and watched by the page-content trigger — edits by anyone but the owner (or an approved editor) are reverted to the snapshot.

Attachment seals protect files; section seals protect PAGE CONTENT. When you seal a section, the app wraps that part of the page in its own bodied macro — manifest key sentinel-vault-sealed-section, titled "Sentinel Vault Sealed Section", described as "Locks the content inside this section against unauthorized edits" — and stores a snapshot of exactly what was inside. From then on, every save of the page is checked: if the sealed body was changed or the whole wrapper was deleted by someone who is neither the seal owner nor an approved editor, the app restores the sealed content and posts a notice. The rest of the page stays fully editable — restoration is surgical, never a whole-page rollback.

The storage triad (mirrors the attachment-seal triad)

section-protection-{sectionId}

The primary seal record: sectionId, pageId, spaceId/spaceKey, lockedBy/lockedByName/lockedByEmail, timestamp, expiresAt, lockDuration, sectionTitle, sealedVersion, contentHash, originalIndex.

section-snapshot-{sectionId}

The guarantee itself: a deep clone of the wrapper node AND the body content as sealed, plus the content hash, the page version and the top-level index. Tamper restoration always restores FROM this snapshot when it exists.

space-section-protection-{spaceId}-{sectionId}

The space-index leg that makes the seal visible in the space console listing: sectionId, pageId, sectionTitle, lockedBy, lockedByName, expiresAt, pageTitle.

section-protection- (content property)

A compact array [{ sectionId, lockedBy, expiresAt }] written onto the PAGE as a Confluence content property. This is the trigger's fast-path probe — pages without it cost one property GET and no body read. It is deleted outright when the page's last section seal goes away (refreshSectionContentProp, section-seals/logic.js).

Section identity

Every seal keys off a stable, app-issued sectionId — crypto.randomUUID(), falling back to sec-<timestamp>-<random> (section-seals/actions.js). It rides inside the macro node's guestParams, and the reader falls back through attrs.parameters.guestParams.sectionId → attrs.parameters.sectionId → attrs.localId (getSectionId, doc-surgery.js). The macro's extension key is derived from the Forge app context as {appId}/{envId}/static/sentinel-vault-sealed-section and cached in the KVS key section-macro-extension-key; every wrapper lookup matches on that key suffix, so a copy of the macro from another app can never pass as a sealed section.

What readers see

On the published page the macro renders the protected body under a "Sealed by Sentinel Vault" shield badge (the app renders the body inline via the ADF renderer when the host supports it). If the inline renderer is unavailable, the frame falls back to the plain notice "This section is protected. Unauthorized edits are automatically reverted."

24Sealing a section: the heading picker

From the panel's Sealed Sections group you pick a heading; the server computes the section's block range, wraps it in the macro, snapshots it and records the seal — all in one write with 409 retry.

The flow, end to end

1. 1Open the Sentinel Vault panel on the page. The "Sealed Sections" group header carries a "Seal a section" button (it toggles to "Cancel" while the picker is open).
2. 2The picker calls the list-page-headings resolver, which reads the page body once and returns every TOP-LEVEL heading as { index, level, text } — shown as an "H1/H2/…" pill plus the heading text, with "(untitled heading)" for an empty one. While loading it shows "Reading page…"; with no headings at all: "No headings to seal. Add a heading, then try again."
3. 3Clicking a row (its call-to-action reads "Seal", then "Sealing…") invokes seal-section with { pageId, headingIndex, headingText }.
4. 4The server re-reads the page, verifies the block at headingIndex still exists and — when a headingText was sent — still has that exact text, computes the section range, deep-clones those blocks, replaces them with one wrapper node, and PUTs the page with the version message "(Sentinel Vault sealed a section)".
5. 5Only after the write lands does it store the seal record, the snapshot, the space-index entry, rebuild the page's section-protection- content property, and touch protections-last-modified so every polling surface picks the change up.

What counts as "the section" (computeSectionRange, section-seals/logic.js)

start = the picked heading
end   = the next heading of the SAME or HIGHER level
        (attrs.level <= picked level), or the end of the page

Sealed = [start, end)  — the heading itself plus everything under it,
         including deeper sub-headings and their content.

A non-heading block seals just itself: { start: index, end: index + 1 }.

Why seal-section can refuse

How long the seal lasts

The hold period resolves exactly like an attachment seal's (resolveHoldPeriod, section-seals/actions.js): an explicit lockDuration override in the payload → the space policy's autoUnlockTimeoutHours x 3600 → the global policy's defaultLockDuration → the baseline of 172,800 seconds (2 days, BASELINE_HOLD_SPAN in shared/baseline.js). The panel's picker sends no override, so panel-sealed sections always get the space/global/default chain. expiresAt is stamped at seal time; the section row in the panel shows "until <date>" — or "Expired" once passed.

25What the snapshot captures

The snapshot is a deep clone of the wrapper node and its body ADF, plus an FNV-1a content hash and the wrapper's top-level position — it is what every restore restores, and what every comparison compares against.

section-snapshot-{sectionId} fields

The hash and its canonical form

hashAdf (doc-surgery.js) stringifies the CANONICAL form of the ADF: every object's keys deep-sorted, and volatile keys — currently exactly localId (VOLATILE_ADF_KEYS) — stripped at any depth. The Confluence editor regenerates localId attrs on every save without any real content change; hashing the raw ADF would make every innocent no-op save of a sealed page look like tampering and trigger a revert storm. A malformed wrapper whose content stringifies to nothing hashes to the sentinel "00000000", which matches no real hash — so a broken copy is treated as CHANGED and restored (fail-closed), instead of throwing and aborting the whole pass.

The fast-path content property

refreshSectionContentProp rebuilds the page's section-protection- property from the live KVS records after every seal and unseal: a compact array of { sectionId, lockedBy, expiresAt }, deleted entirely when no section seals remain. The page-content trigger probes this property FIRST — a page with no property costs one GET and the section pass never reads the body. This is the same fast-path contract the attachment seals keep with their protection- property.

26How tampering is detected

On every page save the trigger groups ALL wrapper copies per sectionId, then judges each seal: a copy is untouched only if its hash matches AND its canonical structure equals the snapshot — a hash match alone is never trusted.

The page-content trigger (pageContentTrigger, triggers.js) runs a single pipeline per save: one body read → ordered in-memory passes (sections first, then media) → one write inside a shared 409-backoff loop. The section pass (restoreSealedSectionsPass) receives the page's seal records — gathered by the content-property probe plus a cursor-paginated scan of section-protection- records (the scan pages in blocks of 100, so an instance with hundreds of sealed sections cannot silently drop one).

The untouched test, exactly (triggers.js)

isUntouched(copy) =
  hashAdf(copy.content) === seal.contentHash
  AND (
    no snapshot bodyContent exists
    OR canonicalize(copy.content) === canonicalize(snapshot.bodyContent)
  )

A seal is judged tampered when ANY copy of its wrapper fails this test.

Duplicate copies all converge

A page can hold DUPLICATE wrappers with the same sectionId — copy-paste, or a crafted REST PUT. The pass groups every wrapper per sectionId (a list, not a last-wins map — it24) and compares EVERY copy against the baseline. On restore, every differing copy gets the sealed body written into the exact node that was inspected; on an approved editor's change, the edited copy becomes the new baseline and every OTHER same-sectionId copy is converged to that accepted body in the same write (it52) — so a duplicate tampered in the same save can neither survive nor later be promoted to the baseline.

A moved section is checked in place, not "restored"

The wrapper locator scans the page DEEPLY (locateBodiedSectionNodes, doc-surgery.js — it25): a sealed section dragged into a layout column, an expand, or a table cell is still found and body-checked exactly where it sits. Without the deep scan a moved section would read as "removed" — the app would splice a phantom top-level clone in AND the nested original would become a permanent blind spot. The seal protects CONTENT; position is only enforced when the wrapper is genuinely gone. The recorded top-level ancestor index is kept solely for positioning a re-insert in that removal case.

27Restore semantics

An edited body is overwritten with the snapshot in place; a deleted wrapper is re-inserted anchored to its preceding heading from the prior version — all inside the pipeline's single surgical write, with notifications only after a confirmed write.

The two violation shapes

Where a removed section is re-inserted

Never at the frozen seal-time index — pages get edited above and below a section, and a frozen index lands in the wrong spot after any structural change (SV-m6). Instead the pass reads version N-1, finds the wrapper there, and takes the BLOCK IMMEDIATELY BEFORE it: if that block is a heading, the wrapper is re-inserted right after the same heading text in the CURRENT body. Failing an anchor match it falls back to the wrapper's position in version N-1, then to the snapshot's originalIndex, then to the end of the page. Insertions are spliced in descending index order so multiple restores never drift each other's positions.

The write, and the honesty rule

All section restores mutate the one in-memory ADF and ride the pipeline's SINGLE write — version message "(Sentinel Vault restored protected content)", written asApp so the loop guard absorbs the re-fired event. The write retries 409 conflicts up to 3 times (500ms/1s/2s). Notifications are dispatched ONLY after a confirmed OK write (SV-M2): if every attempt conflicts or errors, the content is still tampered and the app does not claim otherwise. Each retry attempt rebuilds the notification set from scratch, so a stale claim from a lost attempt can never ship.

Restores are per-section independent

One page save can touch several sealed sections; each is judged and restored independently inside the same pass, and the empty-paragraph rule above guarantees one section's empty baseline can never invalidate the write and take its siblings' restores down with it.

28Owner edits, expiry, and unsealing

The owner edits freely — the trigger silently re-baselines the snapshot to the owner's new content; an expired seal is inert; unsealing unwraps the macro and returns the body to the page.

Owner edits re-baseline (SV-M5)

When the save's actor IS the seal owner, the pass never reverts. If the owner changed the sealed body, the trigger rewrites section-protection- with the new content hash and replaces the snapshot with the owner's new wrapper and body. Without this, the next unrelated save by ANYONE else would compare against the stale hash, "restore" away the owner's own edit, and publicly blame the innocent editor. The re-baseline also touches protections-last-modified — every seal mutation does.

There is also a manual re-baseline resolver

refresh-section-snapshot (section-seals/actions.js) lets the owner re-snapshot on demand — it refuses anyone else with "Only the owner can refresh the snapshot". No UI surface currently calls it; the trigger's automatic re-baseline is the live path, and the resolver exists as a recovery hatch.

Expired seals are inert

The section pass skips any seal whose expiresAt has passed — a dead seal never reverts anyone (the same parity holds on the attachment edit, trash, and media passes). The hourly expiry sweep only NOTIFIES (expiry notice and halfway reminder, each at most once per seal); actual removal of expired records is lazy, done on read or interaction. In the panel, an expired section row shows the meta "Expired" and offers the Unseal button.

What unsealing does (unseal-section)

1. 1Authorize: record owner, or a steward for the seal's space (authorizeSteward).
2. 2Find the wrapper on the page and splice its BODY back in its place — the content survives, only the macro shell disappears. Version message: "(Sentinel Vault unsealed a section)", with the same 3-attempt 409 backoff. If the wrapper is already gone, the page write is skipped and only records are cleaned.
3. 3Delete section-protection-{id} and section-snapshot-{id}, plus the space-index entry.
4. 4Sweep every section edit grant and request for that sectionId (sweepSectionEditAccess) — a later re-seal starts with a clean slate.
5. 5Rebuild the page's section-protection- content property and touch the seal stamp.

29Violation comments and their dedup

Each section tamper posts at most one page comment per (page, sectionId, class) per 24 hours — classes section-removed and section-edited — while the console timeline still records every occurrence.

A restored section produces two records: a dispatch entry (type section-restored for a removed wrapper, section-reverted for an edited body) that fires PER OCCURRENCE and keeps the console timeline truthful, and a page footer comment mentioning the owner and the editor. Only the comment is deduplicated — the marker key is violation-noticed-{pageId}-{sectionId}-{class} with a 24-hour TTL, under the classes section-removed and section-edited (SECTION_NOTICE_CLASSES, triggers.js).

Why the dedup exists

The incident that forced it: a stale editor draft re-publishing every few minutes re-ran the restore and re-posted an identical comment each time — comment spam that buried the page. The dedup was built for the media surface first and the section surface inherited it verbatim (hunt H1-F4), because the same loop was reproducible there.

The claim discipline (postDedupedFootnote)

• The marker is claimed ONLY when the comment channel is actually postable — both ENABLE_CONFLUENCE_BULLETINS and ENABLE_NATIVE_NOTIFICATIONS on. A toggled-off skip never burns the 24h window.
• If the post throws or reports failure, the marker is RELEASED — a transient comment failure must not silence the next real tamper for a day.
• A CLEAN save of the section (every copy matches the seal) clears that section's markers, so the next genuine tamper comments afresh even inside the 24h window.

30Edit requests: the lifecycle

Request (pending, reason up to 300 chars, one per file per requester) → owner approves into a grant that self-expires with the seal, or denies into a 48-hour cooldown; revoke deletes the grant immediately.

A seal protects content FROM everyone else — but collaboration still needs a sanctioned path. Edit requests are that path: a non-owner asks, the owner (or a steward) decides, and an approval mints an edit grant that the enforcement triggers honor. The flow exists twice, in exact parallel: attachments (request-edit-access / approve-edit-request / deny-edit-request / revoke-edit-grant) and sections (request-section-edit / approve-section-edit / deny-section-edit).

The key families (editreq/logic.js)

edit-request-{attachmentId}-{requesterAccountId}

One request per file per requester — status "pending" or "denied" (with deniedAt), carrying the requester's name, the owner, the file name and the trimmed reason (max 300 characters).

edit-grant-{attachmentId}-{editorAccountId}

Active edit authority: editor, grantedBy, grantedAt, expiresAt copied from the seal. Written with a KVS TTL equal to the seal's expiry (setUntil), so the grant self-expires with the seal even if every sweep is missed.

section-edit-request-{sectionId}-{accountId} / section-edit-grant-{sectionId}-{accountId}

The section variants — same shape, same rules, keyed by sectionId.

The lifecycle, compressed

request  -> { status: "pending" } + owner notified (if notifications on)
approve  -> grant written (TTL = seal expiresAt), request DELETED,
            requester notified
deny     -> request kept as { status: "denied", deniedAt }; requester
            notified; re-request blocked for 48h (COOLDOWN_MS)
revoke   -> grant deleted, immediately; no cooldown, no notification
expiry   -> grant's KVS TTL removes it with the seal

The enforcement read is O(1)

getActiveEditGrant(attachmentId, accountId) is a single KVS get plus an expiry check — that is the entire cost the attachment trigger pays to decide whether an editor's change is authorized. The section pass uses the identical getActiveSectionEditGrant. Grant lookups on the media pass only happen for seals that would otherwise be violations, so clean saves stay cheap.

31Requesting edit access (the non-owner's view)

One button on the sealed row cycles Request Edit → Requested → Can Edit or Declined; the server refuses duplicates, self-requests, and re-requests inside the 48-hour cooldown.

On a file or section sealed by someone else, the panel row shows a "Request Edit" button (tooltip on the section variant: "Ask the owner for permission to edit this section"). Clicking it opens an inline reason bar — placeholder "Why do you need to edit this section? (optional)", capped at 300 characters, Enter submits, Escape cancels — with "Send request" / "Cancel" buttons. There is no native browser prompt anywhere in the flow.

The row's four states (exact labels)

Why the server refuses a request

The cooldown is cleaned lazily

A denial keeps the request record with status: "denied" and a deniedAt stamp. The status check (check-edit-request / check-section-edit) deletes the record once 48 hours have passed and reports "none" — so the button simply returns to "Request Edit". Nothing sweeps cooldown records on a schedule; the next check, or any seal teardown, is what removes them.

32Approving and denying (the owner's inbox)

The owner approves in place on the panel row, or across all their seals from the space console's Edit Requests card; approval on an expired seal is rejected, and a grant can only ever be minted against an existing request.

Pending requests surface in TWO places. In the page panel, a sealed row you own grows an inline "Edit requests (N)" block listing each requester by name with their quoted reason and "Approve" / "Deny" buttons (busy states "Approving" / "Denying") — sections use the identical block. In the space console, an "Edit Requests" card aggregates every pending request across ALL attachments you own — its own description: "Approve to let a user edit your sealed file without giving them steward access. Access lasts until the seal expires." It is backed by list-my-edit-requests, which cursor-scans the request keys (pages of 100, up to 10 pages) and filters to your ownership.

Who may act

• The seal owner — the normal case.
• A steward for the seal's space, via the same authorizeSteward check that gates other owner actions (loadSealForOwnerAction / loadSectionForOwnerAction). Everyone else gets "Not the seal owner" / "Not the section owner".

Revoking

The owner's row also lists active grantees under "Editors with access (N)" — each with the grant date ("since <date>") and a "Revoke" button (busy: "Revoking"). Revoke deletes the grant key immediately; the editor's badge falls back to "Request Edit" on their next check, with no cooldown — a revoked editor may ask again at once. Approvals and denials notify the requester (native Confluence notifications, when enabled); revoke sends nothing.

33What an active grant allows

A grantee's change becomes AUTHORITATIVE: attachment edits re-baseline sealedVersion, sealedFileId and the presentation baseline; section edits re-baseline hash and snapshot; even removing the embed is sanctioned — later non-grantee edits revert to the APPROVED content.

A grant does not merely suppress the revert — it moves the baseline (G2). If the app allowed the edit but kept the old baseline, the very next save by anyone else would "restore" the pre-approval content, silently discarding the sanctioned change and blaming an innocent editor. Every grant-honoring path therefore re-baselines in the same breath it allows.

Grantee actions and their re-baselines

What a grant does NOT allow

A grant is edit authority, nothing more. It does not let the grantee unseal, approve or deny other requests, or survive the seal: the grant's KVS TTL equals the seal's expiresAt, and every seal teardown sweeps it. Owner-only and steward-only actions stay owner-only and steward-only.

34Teardown sweeps: nothing survives a seal

Every seal teardown — unseal, steward unseal, purge, permanent delete, expired-seal re-seal, section unseal — deletes ALL grants and requests for that target, so a re-seal starts clean.

sweepEditAccess(attachmentId) deletes every edit-grant-{id}-* and edit-request-{id}-* key (prefix scans, 100 per family); sweepSectionEditAccess(sectionId) does the same for the section families. The invariant (G3): a stale grant surviving into a NEW seal would hand an old requester silent edit rights on a seal they were never approved for — and pending requests carry no TTL at all, so without the sweep a phantom request could surface in the next owner's inbox.

Every path that sweeps

Owner intent on trash is also a teardown of sorts

An owner trashing their OWN sealed file releases the seal — the record converts to an inert trashedOnly tracking record that exists purely so the file stays discoverable in trash listings and restorable from the panel. A non-owner trashing a sealed file is reversed: the app restores the attachment from trash (a new version, history preserved) and keeps the seal. On the app's permanent-delete path the full cleanup runs, sweep included, with an honest "cannot be restored" notice to the owner.

35The state model: Draft, In Review, Approved, Expired

Every page under workflow carries exactly one state from a small state machine. The built-in workflow is Draft → In Review → Approved → Expired, with Approved marked as an enforced state that carries a 150-day review clock.

The workflow engine gives a page a named review state and a defined set of moves between states. The built-in definition (DEFAULT_WORKFLOW in the workflow capsule's logic.js) is called Document Approval and has four states. Each state has an id, a display name, and a color that is a semantic token key (neutral, info, success, critical) — the frontend maps it to brand colors; a definition never stores a hex value.

The built-in Document Approval workflow

The seven transition edges (DEFAULT_WORKFLOW.transitions)

draft      -> in_review
in_review  -> approved     (the enforce/approval gate sits on this edge)
in_review  -> draft
approved   -> draft
approved   -> expired
expired    -> in_review
expired    -> draft

Which definition a space uses

resolveWorkflowDef reads workflow-def-space-{spaceKey} first, falls back to workflow-def-global, and finally to the built-in DEFAULT_WORKFLOW. A stored definition only counts if it has a non-empty states array. Space keys inside KVS keys are passed through the same sanitize regex the sealing capsule uses ([^a-zA-Z0-9:._\s-#] replaced with _).

What a transition validates

validateTransition is a pure function with exact refusal strings: "No workflow definition", "Unknown current state: X", "Unknown target state: X", "Already in that state" (same from and to), and "No transition X → Y" when the edge is not defined. Only moves along a defined edge are ever possible — there is no free-form jump, not even for stewards.

36Where workflow state lives

The page-state record in KVS is the source of truth; a per-space by-state index powers the dashboard and the sweep; a no-TTL transition log is the compliance artifact; a content property mirrors the state for cheap trigger probes.

KVS keys the workflow engine writes (all under storage:app)

The content property

Every persist also mirrors { workflowId, stateId, enteredAt, enforce, approvedVersion } into the page content property sentinel-vault-workflow (best-effort — a failed write is logged, never fatal). This is what makes the enforcement probe cheap: the page-updated trigger reads one content property, and only continues to the KVS record when enforce === true. The property is deliberately separate from sentinel-vault-validation, which belongs to the validations subsystem and has its own rewrite cadence.

The transition log

appendWorkflowLog writes one workflow-log-{pageId}-{ts} entry per state change, with no TTL. getWorkflowLog reads them back with a bounded cursor scan (100 per query, at most 20 pages) and sorts by timestamp. Assignment itself is logged too, with reason "assigned", "auto-assigned on create", or "bulk-assigned" depending on how the page got its workflow.

37Getting pages under workflow

Two ways in: auto-assign on newly created pages (when the space setting is on), and the steward's bulk "Apply to existing pages" which walks the space in batches of 25.

Auto-assign on new pages

When a space has both "Enable document workflow" and "Auto-start workflow on new pages" switched on, the page-content trigger assigns the workflow to every page the moment a created:page event arrives. The phase is gated to created events only — an updated event never auto-assigns — so the setting means exactly "new pages", and backfilling old pages stays an explicit steward action. The page starts at the workflow's initial state (Draft) and the log entry reads "auto-assigned on create".

Bulk-apply to existing pages

The workflow settings tab's "Apply to existing pages" row (button label "Apply to existing pages", "Applying…" while running) starts the workflow on pages that don't have one yet. The resolver refuses unless the space has workflow enabled ("Enable workflow for this space first") and the caller is a steward. Each click processes ONE batch of up to 25 pages (a deliberate cap so the run stays inside the 25-second Forge function budget), skipping pages that already have a workflow.

How the pagination works

The batch lists /wiki/api/v2/spaces/{spaceId}/pages?status=current&limit=25, follows the response's _links.next cursor, and returns { assigned, scanned, capped, nextCursor }. The UI keeps the cursor in component state, so the result message tells you whether to keep going: "Applied the workflow to N pages (25 scanned — run again to continue)." — clicking again resumes from the cursor instead of rescanning from the start. When capped is false the cursor resets and the space is done.

38Moving a page: the ribbon state chip

The page's state is a solid colored pill on the Sentinel Vault ribbon. If moves are available it becomes a menu button with full keyboard support; a blocked transition shows the server's exact reason inline.

On any page with a workflow, the ribbon shows a pill with a flag icon and the state name, colored by the state's semantic token (class wf-chip-{color}). Its tooltip reads "Document Approval — In Review (click to move)" — the "(click to move)" suffix appears only when the current state has outgoing transitions. A page whose state has no available moves renders the pill disabled; a page with no workflow renders no chip at all.

The move menu

Clicking the pill opens a custom dropdown (never a native select) headed "Move to…", one row per reachable state with a colored dot. A target that will open an approval instead of moving immediately is labelled "Request approval → Approved" — the server flags a transition with requiresApproval when the target is an enforce state and the space has approvers configured, so the label never over- or under-promises.

Keyboard support (ARIA menu pattern)

• Opening the menu moves focus to the first item; ArrowDown / ArrowUp cycle with wrap-around, Home / End jump to the ends.
• Escape closes the menu and returns focus to the pill; clicking outside or tabbing away also closes it.
• After a transition completes (or fails), focus returns to the pill, and a successful move replays a short "seat" animation on the newly rendered state.

When a move is refused

The resolver's reason is shown inline next to the chip (role="alert"): "Entering \"Approved\" requires steward approval" for a non-steward hitting the enforce gate, validateTransition's "No transition X → Y" family for an illegal edge, or "Page has no workflow assigned". A content-conditions block goes further — the error joins the reason with the specific failures: "This page doesn't yet meet the content requirements for that state. — <first rule message>; <second rule message>".

39Approvers and decision rules

A space can require named people and/or whole groups to sign off before a page reaches Approved. Groups are expanded to their members at request time, and the quorum rule is any-one, all, or a minimum count.

The settings row "Require approval to reach Approved" turns the In Review → Approved edge from a steward gate into a multi-approver approval. Its description states the behavior exactly: "Instead of moving straight to Approved, require the people below to sign off first. Until they do, the page stays In Review and shows 'Awaiting approval' on its ribbon." Approvers are picked with search-as-you-type pickers (debounced 300 ms, Confluence user search / group picker, 8 results) — one for people, one for groups.

Decision rules (settings.approval.mode)

How groups become approvers

At request time, resolveApproverIds expands each configured group via /wiki/rest/api/group/member?name={group}&limit=100 and unions the member account ids with the named users (deduplicated). The effective min is clamped to the resolved approver count, so a minimum of 3 over 2 resolvable approvers cannot instantly deny on the first vote. A group whose expansion FAILS (as opposed to a genuinely empty group) sets an unresolved flag — enforcement then trusts the approver snapshot rather than treating a real approver as a stranger during a group-service outage.

40The approval round, end to end

Requesting Approved pins the exact page version being reviewed, opens one vote record per approver, @mentions them in a page comment, and completes or clears the transition when the quorum resolves — refusing to complete if the page changed under review.

What happens when someone clicks "Request approval → Approved"

1. 1The engine validates the edge, then captures the live page version as pinnedVersion — this is the version the approvers are approving. If the version cannot be read the request fails closed: "Could not verify the page version — please retry."
2. 2One workflow-approval-… record per approver (status "pending") plus one workflow-pending-{pageId} record are written, carrying the target state, requester, mode, min and the pinned version.
3. 3A footer comment is posted on the page — "🛡️ Sentinel Vault — Approval requested" — that @mentions every approver, names the requester and target state, and states the rule ("any one of you can approve" / "all of you must approve" / "at least N of you must approve"), so Confluence's own notification engine emails them with no external egress.
4. 4The ribbon chip flips to amber: "Awaiting your approval" if you are a pending approver, otherwise "Awaiting approval", with a live "N of M" count.
5. 5Approvers decide from the chip's dialog or from the "Approvals waiting on you" inbox in the space console. When the quorum rule resolves, the transition completes (or, on denial, the round is cleared and the page stays In Review). The requester gets a resolution comment: "your request to move this page to Approved was approved/declined by <decider>."

The approval dialog

Clicking the awaiting chip opens a dialog headed "Approval to move to Approved", subtitled "Requested by <name> · <rule text>", with a progress line "N of M approved" and one row per approver showing a solid status badge (Approved / Denied / Pending), their name ("(you)" appended for the viewer) and their reason in quotes if they gave one. A pending approver additionally sees an outcome line that says exactly what their click will do — "You're the deciding approval — approving moves this page to Approved." when their vote completes the quorum, otherwise "Approving records your sign-off; the page moves once the rule is met." — plus "Denying keeps it In Review.", an optional reason textarea ("Add a reason (optional)"), and Approve / Deny buttons. Everyone else sees "You have already responded." or "Waiting on the approvers above."

The approvals inbox

The space console renders an "Approvals waiting on you" panel (with a count) whenever the current user has pending votes — and renders nothing at all otherwise. Each row links the page title, says "Move to Approved · requested by <name>", and offers inline Approve / Deny. The list is bounded to 25 items, drops rows whose round has since resolved, and hides items whose AI review has already failed — a currently-blocked request should not nag approvers.

Re-requesting while a round is open

A second transition request on a page with an open round is refused ("An approval is already pending for this page") unless it comes from the original requester or a steward — so one colleague cannot silently discard the approvers' in-flight review by re-requesting.

41Entry conditions: content rules and the AI review

A target state can require the space's validation rules to pass (checked synchronously, blockers listed) and/or an AI content review that acts as one more approver — AND-composed with the human quorum on the same pinned version.

Per-target-state entry conditions live in settings.entryConditions as { requireRules, requireAi, aiThreshold, onBudgetExhausted }; the settings UI exposes them for the Approved state as "Require content rules before Approved" and "Require an AI content review before Approved". Conditions run BEFORE the enforce/approval branch — a page that fails them never even opens an approval round.

Content rules — synchronous, with named blockers

The rules gate reuses the space's Validations ruleset verbatim and evaluates it in the resolver call itself: required headings, tables, labels, length limits. Only block-severity violations block. The refusal names them: "This page doesn't yet meet the content requirements for that state." followed by each violation message in the ribbon error. It fails closed — if the page body cannot be read, the move is refused with "Could not read the page to check content conditions — please retry." rather than waved through unchecked. Deliberately, the gate uses the authored rules INDEPENDENT of the space-wide post-save validation master switch: a steward asking for a transition condition must not silently no-op because the separate always-on validation happens to be off.

The AI review — one more approver

With "Require an AI content review" on, the request writes an aiGate axis onto the SAME pending record as the human votes and enqueues a review of the SAME pinned version on the ai-validation-queue (Forge LLM — no external egress). The dialog shows it as an extra row named "AI content review" with a badge: Reviewing / Passed / Issues, plus the model's reason in quotes when it has one. The transition completes only when the human quorum AND the AI have both passed: humans done but AI still running yields "Approvals complete — waiting on the AI content review."; an AI failure yields "AI content review did not pass — revise and re-request."

Degraded-mode behavior (resolved without an LLM call)

Strictness

"AI review strictness" maps to the threshold: Strict (flag any issue) = low, Balanced = medium (the default), Lenient (serious issues only) = high. Verdict application is CAS-guarded — it only ever flips the gate from "pending", so a duplicate worker delivery or a reaper-vs-worker race is a no-op.

42ENFORCED Approved: what happens to an unapproved edit

Approved is not a label — it is enforced. When someone who is neither an approver nor a steward edits an Approved page, the app either demotes the page back to Draft (default, keeps the edit) or reverts the body to the approved version (opt-in, stricter).

This is the app's differentiator over status-macro workflows: the Approved state actively defends itself. The page-updated trigger runs a cheap probe first (one read of the sentinel-vault-workflow content property — no page-body read), then confirms against the authoritative KVS record and the space's definition that the page really is in an enforce state, and classifies the editor.

Who counts as privileged on an enforced page

Approver

The editor is in the approver SNAPSHOT taken when the page entered Approved, AND still in the live approver config (snapshot ∩ live — so revoking an approver takes effect immediately). If live group expansion failed (outage), the snapshot alone is trusted rather than reverting a real approver's edit.

Steward

A space steward, resolved with the trigger-safe check (explicit steward list, steward groups, site admin, or space ADMINISTER permission — all evaluated as the app, since triggers have no user context).

The app itself

Sentinel Vault's own writes (a revert re-save, a seal restore) are recognized by the app's account id and NEVER trip enforcement — and if that account id cannot be resolved, enforcement is skipped for the run rather than risking an unbounded revert loop.

The two enforce modes (settings.enforceMode)

How a revert avoids destroying legitimate work

The revert pass runs FIRST in the body-protection pipeline (before seal restoration, which it short-circuits — the whole body is being replaced anyway). It does not blindly restore the baseline version: if versions exist between the baseline and the tamper, it finds the HIGHEST intervening version authored by a privileged actor and reverts to that, so a concurrent approver edit sandwiched under the tamper is not destroyed. Two hard guards: an empty or unreadable baseline body aborts the revert (a protection feature must never blank a page), and if the current body already equals the approved body — checked by hash AND canonical structural compare, since a 32-bit hash match alone is not proof — nothing is written at all.

43The approved baseline (approvedVersion)

Enforcement anchors on approvedVersion — the page version an actual authority reviewed. It is captured fail-closed at approval time, only ever advances on sanctioned events, and is never guessed.

When a page enters Approved, the record stores approvedVersion (the pinned version the quorum approved, or the live version the steward acted on for a direct steward move), an approvers snapshot, approvedAt, and approvedBy. Leaving the enforce state clears all of it. If the live version cannot be read at approval time the transition FAILS ("Could not verify the page version — please retry.") rather than entering Approved with no baseline — a null baseline would make enforcement meaningless.

The only events that move the baseline forward

• A quorum-approved transition — the baseline becomes the pinned version the approvers actually reviewed.
• A privileged (approver/steward) edit — reconciliation advances the baseline to the version they wrote.
• The app's own confirmed revert write — the baseline becomes the version the revert produced.
• A confirmed observed equality — the revert pass proved the body already equals the approved body, so the version bump is sanctioned.
• The sweep's self-heal — an enforced page found with a null baseline is stamped with the live version instead of being skipped (better a late anchor than none).

Forward-only re-stamping

restampApprovedVersion is the single re-stamp primitive: it refuses to move the baseline backward (a late or re-delivered event with an older version is ignored), re-reads the record immediately before persisting so it never clobbers a concurrent demote, and only applies while the page is still in an enforce state. Creating a seal on an enforced page also advances the baseline to the live version — so a later whole-page revert restores the seal instead of stripping it.

44The hourly sweep: the durable backstop

Forge events can drop. The workflow-sweep-scheduled trigger walks the by-state index every hour, expires overdue approvals, catches missed tampers author-aware, self-heals missing baselines, and reaps stuck AI reviews.

workflowSweep (manifest: scheduledTrigger workflow-sweep-scheduled, interval hour, function workflow-sweep-fn) scans every workflow-idx-… row in bounded cursor pages (100 per query, up to 20 pages per run). Per-space workflow definitions are cached across the run, since most pages in a space share one.

Per page, in order

1. 1Review expiry FIRST: an Approved page whose reviewDueAt has passed is auto-transitioned to Expired (reason "review period elapsed — auto-expired") with an "Approval expired" comment. Leaving Approved also ends enforcement, so the page needs nothing else this tick.
2. 2Non-enforced pages are done. For enforced pages, read the live version; unreadable → skip this tick (never act on a guess).
3. 3Null baseline on an enforced page is a hole, not a skip: self-heal by stamping the live version.
4. 4Live version equals the baseline: no drift — clear any leftover integrity-notified marker and move on.
5. 5DRIFT: fetch the top version's author. The app's own account, a snapshot∩live approver, or a steward means the drift was an AUTHORIZED edit whose event was dropped — advance the baseline instead of punishing it.
6. 6Unauthorized drift: revert mode (with a non-empty approver snapshot) re-applies the approved body — three attempts with exponential backoff on 409 version conflicts, and a body already equal to the baseline just advances the baseline without a destructive rewrite. Otherwise demote to Draft (reason "auto-demoted by integrity sweep (unauthorized drift)").

The AI reaper

The same run scans workflow-pending-… records for AI gates still "pending" more than 15 minutes after enqueue — a lost worker delivery — and fails them terminally ("AI review timed out — please re-request."). The verdict application is CAS-guarded, so a late worker that already resolved the gate makes the reaper a no-op. The sweep returns its tally as { reverted, demoted, healed, expired, aiTimedOut }.

45Review dates and auto-expiry

Approved carries a review clock — 150 days by default, per-space overridable — shown on the ribbon as "Review due <date>" and flipping to "Review overdue" before the sweep moves the page to Expired.

When a page enters a state with a review clock, computeReviewDueAt stamps reviewDueAt = now + days. The days come from the steward's per-space override ("Re-review Approved pages after — N days") when set, else the state's built-in reviewAfterDays — 150 for Approved in the default workflow. States without a clock (Draft, In Review, Expired) get no due date. Settings are only read when the target state actually has a clock, keeping every other transition cheap.

What you see on the ribbon

Next to the state chip, a page with a due date shows "Review due Mar 5" (tooltip: "Approval is due for re-review on <full date>."). Once the date passes it becomes "Review overdue" with the tooltip "The review period has elapsed — this page will move to Expired." — an honest statement, because the transition is the hourly sweep's job, not the ribbon's.

Expiry

The sweep auto-transitions an overdue Approved page to Expired with the log reason "review period elapsed — auto-expired" and posts a comment @mentioning whoever put the page into Approved: "Approval expired — this page's review period has elapsed, so Sentinel Vault moved it to Expired. Re-submit it for review to approve it again." From Expired, the workflow offers edges back to In Review or Draft, so re-approval follows the normal path — including the full approval round if one is configured.

46The space workflow dashboard

The Workflow tab in the space console shows exact per-state counts and the overdue tally computed entirely from the by-state index — no per-page reads — plus the 100 most recently changed pages and a client-side CSV export.

The dashboard ("Workflow status", subtitle "N pages under workflow in this space.") is read-only and steward-visible on the space console's Workflow tab. It reads every workflow-idx-{space}-… row in bounded pages (100 per query, up to 30 pages — about 3,000 pages of coverage) and derives everything from those rows: one solid-colored stat tile per workflow state with its exact count, plus a "Review overdue" tile whenever any Approved page's reviewDueAt is in the past.

The recent-pages table

Below the tiles, a table lists the most recently changed pages — sorted by enteredAt descending, capped at 100 (LIST_CAP) — with columns Page (linked title), State (colored chip), Entered, and Review due ("<date> · overdue" in red when past). Titles are the ONLY thing fetched per page, in parallel and only for the listed 100; a page whose title cannot be read renders as "(page <id>)" rather than vanishing. When the space holds more than 100 workflow pages, a note keeps the numbers honest: "Showing the 100 most recently updated pages. The counts above cover all N."

CSV export

"Export CSV" builds the file in the browser from the already-loaded table data — no server round-trip, no egress — and downloads it as workflow-<spaceKey>.csv. Columns: Page ID, Title, State, Entered, Review due, Overdue ("yes" or blank); every value is quoted with doubled inner quotes, CRLF line endings. It exports the listed pages, i.e. at most the 100 the table shows.

47The workflow settings tab, row by row

Everything a steward configures lives on one settings panel in the space console. Per-space settings need a steward of that space; the global workflow definition needs a site admin.

Every row on the panel (exact labels)

Saving

"Save workflow settings" writes the whole panel via set-space-workflow-settings, which is steward-gated ("Only a space steward can change workflow settings"). The UI checks the resolver's actual result — success shows "Workflow settings saved.", a refusal or failure shows the reason instead of a false success. The stored shape is normalized server-side: unknown enforce modes fall back to demote, non-positive review overrides become null, entry-condition entries that require nothing are dropped, and approver entries without an id are filtered out.

48What Conditions & Validations is

A rules engine that checks every page save against admin-authored content standards, three escalating enforcement modes, and an optional AI content review that runs entirely on Atlassian infrastructure.

Conditions & Validations is Sentinel Vault's page-quality layer. Admins author structural rules ("every page needs a heading containing Overview", "at least one table", "labels x and y", "no more than 20,000 characters") and pick how violations are handled: a comment on the page (advisory), a recorded pass/fail status (gate), or an automatic roll-back to the last compliant version (hard revert). Separately, Semantic AI Validations reviews page content against plain-language rules, a style guide, tone requirements and compliance standards — using Atlassian-hosted Claude via the Forge llm module, with zero external egress.

Where the feature lives

Global config

Confluence Settings → Sentinel Vault Admin → the Validations tab. Renders the shared ValidationsEditor at global scope; saving requires a site admin (the resolver rejects anyone else with "Not authorized — steward or admin access required.").

Space config

The Sentinel Vault space page → Validations tab, visible to stewards of that space. Same editor at space scope; a steward of the space (or a site admin) can save.

The page panel

The Sentinel Vault macro on a page grows two groups: Validation (gate status + a Re-check button) and AI Review (Run AI review + the findings list with triage buttons).

The page ribbon

Status chips: "Validation: passed" / "Validation: issues" / "Validation: awaiting approval", and "AI check: N findings" when the latest AI run found anything.

The deterministic rules and the AI review are deliberately separate systems. The rules engine (src/server/infra/rules-engine.js) is pure and synchronous — same page, same rules, same verdict, every time — and runs automatically on save. The AI review is opt-in, manual-first (a page save never spends tokens by itself), asynchronous, and explicitly non-deterministic.

49The rule types

Seven rule types in the engine, six offered in the editor; each rule carries a type, a report label, a severity (Recommended or Required), and a small type-specific config.

"+ Add rule" in the editor creates a rule with type required-heading and severity warn. Each rule card has a type dropdown, a severity dropdown, a remove button, a label input (placeholder: "Label (shown in the report)") and the type's own config fields. A rule is stored as { id, type, label, severity, config } — the id is r<timestamp> and the label is what violation reports display (falling back to the raw type name).

Rule types (rules-engine.js)

A rule stored with enabled: false is skipped, and a rule whose evaluation throws is treated as passing (logged, never fatal) — one broken rule cannot take down the validation run.

50When validation runs

On every page create and update event, after the seal-protection pipeline, exactly once per (pageId, version) — with an up-front dedup claim so duplicate event deliveries cannot double-post.

The page-content-events trigger (manifest events avi:confluence:updated:page and avi:confluence:created:page) runs the validation phase after the sealed-file / sealed-section / enforced-state pipeline finishes, and independently of it — a page with no seals at all is still validated.

Preconditions — all must hold or the phase exits silently (runValidationPhase, triggers.js)

1. resolveEffectiveConfig(spaceKey).enabled === true   (global master switch ON)
2. effective rules array is non-empty
3. pageData.status === "current"                       (drafts / archived pages are never enforced)
4. the page version number is defined                  (an undefined version would bypass dedup)
5. this (pageId, version) has not already been checked

The once-per-version guarantee

Before any side effect, the phase writes a dedup marker validation-checked-{pageId}-{version} (30-day TTL). Claiming the marker FIRST means a duplicate updated:page delivery for the same version — Forge events are at-least-once — cannot post the advisory comment twice or double-write the gate state.

Last-good tracking

When a version passes (no Required-severity violations), the phase records it as the page's last known good version in validation-lastgood-{pageId}. This pointer is what hard-revert mode rolls back to. It only advances on saves made while validation is enabled — history from before the feature was turned on is invisible to it.

51The three enforcement modes

Advisory, gate and hard-revert are independent checkboxes that combine; the effective set for a space is always the UNION of global and space modes.

Enforcement modes (exact checkbox labels from the editor)

The gate status is stored as the content property sentinel-vault-validation on the page (shape: { state, violations, version, checkedAt }). Because it is a content property it is CQL-queryable — you can build a Confluence search for every page currently failing validation.

52Anatomy of a validation comment

One footer comment per failing version, posted by the app, mentioning the editor, with a severity chip per violation and — after a revert — a recovery link into the page history.

Validation comments are Confluence footer comments authored by the app (validation-blueprints.js), opening with the "🔒 Sentinel Vault — Content Validation" header and an @-mention of the person whose save failed. A comment is only posted when there is at least one violation to report.

The two lead lines

not reverted:  "Your recent edit does not meet this page's content standards. Please review and update:"
reverted:      "Your recent edit did not meet this page's content standards and was reverted to the last compliant version."

Each violation renders as one list item: "⛔ Required — <rule label>: <message>" for block-severity rules, "⚠️ Recommended — <rule label>: <message>" for advisory ones. All text is XML-escaped before it enters the comment body.

53How hard-revert works

Revert writes a NEW page version whose body is the last compliant version's body — guarded against concurrent saves, retried on conflicts, and always explained in one comment.

A revert is not a version deletion. The app reads the body of the last-good version and PUTs it as a fresh version on top, with the version message "(Sentinel Vault reverted non-compliant content)". The author's edit remains one version down in the history, which is exactly where the comment's recovery link points.

Guards on the revert write

eligible      lastGood exists AND lastGood < failing version
race check    re-read the page before writing; if the live version number
              no longer equals the version that was evaluated, ABORT —
              a newer concurrent save gets its own validation pass instead
              of being overwritten with stale content
conflicts     up to 3 attempts; a 409 waits 2^attempt x 500 ms and retries
failure       any other error aborts silently (logged) — never a loop

After a successful revert

• The single "was reverted" comment is posted — even when advisory mode is off, so the author always learns their edit was rolled back and how to recover it.
• If gate mode is on, the validation property is reconciled to "passed" for the new (restored) version — the panel and ribbon don't keep showing a stale "Issues found" for content that is compliant again.
• The restored version will itself fire the page-update trigger; the dedup marker and the app's own-write recognition keep that from cascading.

54Global vs space config, and the compliance floor

Global is the master switch; a space refines rules on top of it but can only STRENGTHEN enforcement — global Required rules and globally-enabled modes always apply.

Config lives in two KVS documents: validation-config-global and validation-config-space-{spaceKey}. The global document's enabled flag is the master switch for post-save validation — when it is off, resolveEffectiveConfig returns disabled and NO space is validated on save, regardless of any space config. A space cannot opt itself in while the organisation switch is off.

The merge, exactly (logic.js)

rules  space has NO rules  -> inherit ALL global rules (block + warn)
       space HAS rules     -> global block-severity rules ALWAYS apply (the floor),
                              space rules are added on top; space rules REPLACE the
                              global advisory (warn) rules
modes  advisory/gate/revert are each the UNION of global and space —
       a space can turn a mode ON, never OFF
ai     a space ai config with an explicit enabled flag overrides global ai
       entirely; otherwise global ai applies

The floor exists so a space can never silently drop an org-mandatory rule: a space steward authoring their own ruleset still inherits every global "Required" rule, and an advisory-only space cannot defeat an org-mandated gate or revert. The space editor states this in its own copy: "These rules apply to this space, on top of the organisation's required (blocking) global rules — which always apply. Your rules replace the advisory global rules; leave empty to inherit all global rules."

A space config saved with its own "Enable content validation" toggle OFF is ignored entirely — treated as if no space config existed, so the space inherits full global enforcement. This closes a real bug: merely opening the space Validations tab used to persist a dormant disabled shell that silently downgraded the global modes.

55The panel's Validation group and "Re-check"

A read-only on-demand check from the Sentinel Vault panel: it evaluates the live page against the effective rules and shows the result inline — it writes nothing and posts nothing.

The Validation group appears in the Sentinel Vault panel only when a gate status exists for the page (pages that have never been gated stay clean). The header shows a badge — "Passed", "Issues found", or "Awaiting approval" — and a "Re-check" button (busy label: "Checking").

Re-check calls the validate-page-now action: it resolves the effective rules for the space (independent of the global master switch), reads the live page body and labels, runs the engine, and returns the verdict to the panel. No comment is posted, no gate state is written, no version is marked checked — it is purely informational. With no rules configured it reports "No validation rules configured."; with a clean result, "All checks passed."

The page ribbon mirrors the stored gate state as a chip ("Validation: passed" / "Validation: issues" / "Validation: awaiting approval"). There is also a steward-only approve-page-gate action that stamps the state to passed with the approver's account id recorded — authorization is checked against the page's REAL space, resolved server-side from the page id, never from a caller-supplied space key. It is currently a resolver-level action; the panel has no button for it.

56Semantic AI Validations: the architecture

AI review runs on Atlassian-hosted Claude through the Forge llm module — no API keys, no data egress — asynchronously on a queue, restricted to the Haiku model family by a three-layer backstop, and OFF by default.

The manifest declares an llm module (sentinel-vault-llm, model claude), which is Atlassian's Forge LLMs platform: the model runs inside Atlassian's infrastructure, so page content never leaves the platform and the app keeps its "Runs on Atlassian" posture. The editor's own description: "AI review uses Atlassian-hosted Claude via Forge — no external API keys and no data egress. Token usage is billed to this app's Forge account, so AI is off by default and limited to Claude Haiku."

The moving parts

The Haiku-only backstop is enforced three times

list   listForgeLlmModels() filters the platform's model list to /haiku/i
save   store-validation-config resets any non-Haiku ai.model to the default
chat   callForgeLlmChat() clamps a non-Haiku model to the default at call time
-- so even a stale or hand-edited config can never bill a larger model

AI is manual-first: the page-save trigger never enqueues an AI review on its own. Tokens are only spent when someone presses "Run AI review" in the panel, or when a workflow transition is configured to require an AI review as an entry condition.

57Running an AI review

Steward-only, budget-checked, queued with a pollable task id; the worker extracts the page text, builds the policy prompt, calls the model, and stores capped, normalized findings.

"Run AI review" (or "Re-run AI review" once findings exist; busy label "Reviewing") calls enqueue-page-validation. Only a steward of the page's space may run it — the space is resolved server-side from the page id, because a review spends that space's token budget and must not be triggerable against someone else's budget. Non-stewards get "Only a steward of this page's space can run an AI review"; with AI off, "AI validation is not enabled. An admin can turn it on in Sentinel Vault settings."; over budget, "This space has reached its monthly AI token budget."

Lifecycle of one review

1. 1The action mints a task id (aival_<timestamp>_<random>), writes a queued status row (ai-validation-status-{taskId}, 1-hour TTL) and pushes the job onto ai-validation-queue.
2. 2The panel polls get-validation-job every 1.5 s, up to 40 tries (~60 s), then gives up with "AI review timed out." — the job itself keeps running and its result still lands.
3. 3The worker resolves the AI config, clamps the model to Haiku, reads the page body and title, extracts plain text and truncates it to maxChars (default 40,000 characters).
4. 4It builds the policy prompt from your configured rules / style guide / tone / compliance standards, calls the model in JSON mode, and accrues the token usage against the space's monthly counter.
5. 5Findings are normalized and stored (ai-latest-{pageId} for the panel, plus a timestamped ai-finding-{pageId}-{ts} audit copy kept 90 days), the status row flips to done, and the panel renders the list.

One finding, normalized (normalizeFindings)

Author notification

With "Notify page author" on, findings at or above the configured severity threshold are posted as a footer comment — header "🔒 Sentinel Vault — AI Content Review", mentioning the author of the page's current version (falling back to whoever requested the review), one line per finding with a 🔴 High / 🟠 Medium / 🟡 Low chip, the verbatim excerpt in quotes, and a "Suggestion:" line when the model offered a fix.

58AI configuration fields

What each field in the Semantic AI Validations block does, how the four policy texts become the review prompt, and how the monthly token budget is enforced.

The AI config (editor labels; stored under the config's ai object)

The four policy texts are pasted into the reviewer prompt under literal "## Custom rules", "## Style guide", "## Tone / voice requirements" and "## Compliance standards" headings (empty ones read "None configured"), followed by a strict output contract: a single JSON object of findings with severity, category, ruleRef, a verbatim excerpt, a one-sentence explanation and a concrete suggestion — and the instruction "Do not invent violations."

Budget accounting

Usage accrues per space per UTC month (ai-usage-{spaceKey}-{YYYYMM}: input, output and total tokens plus a run count, kept 120 days). Every review — manual or workflow-gate — accrues, including failed parses. The budget is checked BEFORE a job is enqueued; a run already in flight when the budget trips completes normally, so a month can end slightly over budget.

59Triaging findings: dismiss and false-positive

Per-finding states with stable ids that survive re-runs, hidden-findings recall, and one honest caveat about the ribbon count.

Each open finding in the AI Review group shows its severity, ruleRef, explanation and suggestion, plus two buttons: "Dismiss" and "False positive". Both hide the finding from the open list (a dismissed/false-positive tag replaces the buttons with "Restore"); "Show N dismissed" reveals the hidden set. The group's count chip counts OPEN findings only.

Finding ids are content-derived — a hash over category, ruleRef, excerpt and explanation — so a re-run that reproduces the same finding reuses the same id, and your dismissal sticks. The flip side: if the model re-words its explanation or picks a slightly different excerpt for the same underlying issue, that is a NEW id and the finding reappears as open.

The four states (set-ai-finding-state)

• open — the default; the only state with Dismiss / False positive buttons.
• dismissed — hidden from the open list; restorable.
• false-positive — hidden, tagged "false positive"; restorable. Semantically distinct so a future accuracy report can separate noise from real-but-ignored.
• acknowledged — accepted server-side but no panel button sets it; it renders like an open finding.

60Honest limits of the AI review

Non-deterministic verdicts, fail-closed handling of unreadable model output, truncation on both ends of the call, and a bounded retry policy.

The AI review is advisory by nature: the same page against the same config can produce different findings on different runs — different counts, different excerpts, different severities. The deterministic rules engine, not the AI, is the right tool for anything that must be exactly reproducible. Treat AI findings as a reviewer's notes, not a verdict.

Failure behavior, exactly

Transient errors — 429 rate limits, 408s, 5xx, network resets — are retried up to 3 extra attempts with exponential backoff (400 ms doubling, capped at 2 s). Model output is recovered by a tolerant JSON parser that strips markdown fences, extracts the first balanced JSON block, and repairs unescaped quotes and truncation before giving up and returning null.

61Validations as workflow transition conditions

A workflow state can require the page to pass the block-severity rules — and optionally an AI review of the exact reviewed version — before the transition completes. The mechanics live in the Workflow part; the validation semantics are summarized here.

Two entry conditions on a workflow target state reuse this machinery. The content condition runs the deterministic engine synchronously at transition time: it resolves the effective rules (global floor included, and INDEPENDENT of the validation master switch), evaluates the live page, and blocks on any Required-severity violation with "This page doesn't yet meet the content requirements for that state." — returning only the blocking violations. A page-read failure blocks too: unverifiable content is never let through.

The AI condition rides the same ai-validation-queue as manual reviews, in gate mode. It reviews the PINNED version — the exact bytes the human approvers saw — not whatever the page looks like when the worker runs. Findings at or above the state's configured threshold (default medium) fail the gate, with a reason like "2 issue(s): <ruleRef>; <ruleRef>"; the ribbon's approval card shows the AI reviewer as its own row: "Reviewing" → "Passed" / "Issues".

AI-gate resolutions that never call the model

62The two consoles, and who sees what

Sentinel Vault has a per-space console (Space Preferences) and a site-wide console (Sentinel Vault Admin); space stewards get six tabs in the first, site admins configure everything else in the second.

Where administration lives

The space console's steward gating is enforced by the app, not by the manifest — the module is a plain space page, so any space member can open it. On load the console calls the check-user-role resolver, which runs isOperatorSteward; a steward result unlocks the Sealed Files, Access Control, Seal Duration, Macro, Validations and Workflow tabs, anything else shows only My Sealed Files. The role check deliberately ignores the force-unseal toggle (allowAdminOverride), so stewards keep their tabs even when force-unseal is globally disabled — only the Force Unseal button itself disappears.

Both consoles save through the same store-policy resolver and the same button, labelled Apply Configuration ("Updating..." while in flight). A save that the backend refuses for authorization reasons returns { success: false, reason } rather than throwing, and the console shows that reason instead of a false "updated" message. On the space console the button renders on every tab except Validations and Workflow, which carry their own editors and their own save buttons.

63Space console: the My Sealed Files tab

The non-steward view lists the caller's own seals across the instance with an Unseal button, hosts the Edit Requests inbox, and carries the steward-access request banner with its 48-hour deny cooldown.

For a regular user the space console opens on My Sealed Files. It calls enumerate-operator-seals (limit 50) — a listing of every seal the caller owns — and renders each as a card with a status lozenge of My Seal (or Overdue once expiresAt has passed), the page title, space, seal date and time remaining, plus an Unseal button ("Release your seal and allow others to modify this file"). Expanding a card shows an inline thumbnail for images and View / Properties links into Confluence. The empty state reads "You have no sealed files in this space."

Requesting steward access

A user with no pending request sees a banner: "Want to manage all sealed files in this space? As a steward you can view all sealed files and force unseal them when needed." with a Request Steward Access button. Pressing it writes a steward-request-{spaceKey}-{accountId} record with status pending; the banner flips to "Your steward access request has been submitted. A space admin or steward will review it."

After a denial: the 48-hour cooldown

A denied request keeps its record with status denied and a deniedAt timestamp. The banner then says "Your steward access request was denied." and counts down: "You can submit a new request in about N hours/days." The cooldown is exactly 48 hours (cooldownMs = 48 * 60 * 60 * 1000 in check-steward-request), enforced lazily — the next time the user opens the console after 48 hours, the denied record is deleted and the request banner returns.

The Edit Requests inbox

When other users have asked to edit files the caller has sealed, a card titled Edit Requests appears above the seal list (it renders nothing when empty). Its own description states the model: "Approve to let a user edit your sealed file without giving them steward access. Access lasts until the seal expires." Each request shows the requester, the file name and the request date, with Approve / Deny buttons. Approve writes a grant whose KVS TTL equals the seal's expiry, so the grant self-destructs with the seal; Deny puts that requester on their own 48-hour cooldown for that file.

64Space console: the Sealed Files tab (stewards)

The steward listing shows every seal in the space as sortable, column-configurable cards, live-probes each row for stale state (Trash / Missing / Overdue badges), and pages with a Show more button.

The tab is headed "Sealed Files in <space name>". Data comes from enumerate-realm-seals, a cursor-paged read of the space-protection-{spaceId}-* index (page size capped at 100 server-side; the console asks for 10 per page by default). A toolbar carries a Properties column picker (Name, Status, Sealed by, Location, File Size, Sealed on, Expires, Actions — Name and Actions are always on; File Size and Sealed on are off by default), a sort picker (Name, Sealed by, Location, Sealed on, Expires — ascending/descending toggles on re-click, sorting is client-side over the loaded rows), and a live "N sealed files" count.

Status lozenges on a sealed-file card

How the stale badges are computed

After each page of index rows loads, the console probes each attachment's real status via probeAttachmentStatus in chunks of 10 concurrent probes, bounded to the one page of rows just fetched. A probe failure deliberately renders the row as non-stale — the same fallback the inline panel uses, so the two surfaces can never disagree about the same file. This probe pass exists because of a real incident (2026-07-22) where the console listed a trashed attachment's seal as a normal live row.

Pagination

More rows load two ways: scrolling within 100px of the list bottom triggers the next page automatically (debounced 150 ms), and an explicit Show more button renders whenever a next cursor exists. Skeleton cards show while a page loads. When the cursor is exhausted the list ends with the italic line "All sealed files shown". Changing the page size resets the list and refetches from the start.

Row actions

Each card offers Watch ("Get notified when this file is unsealed" — toggles to Watching; the watch request lives 7 days) and, when steward override is enabled, Force Unseal ("Override the seal as a steward and release this file"). Success shows "File seal cleared!" and reloads the list. The Force Unseal button disappears entirely — for every steward — when the global Allow Steward Force-Unseal toggle is off; the console checks steward-override-enabled on load.

65Space console: the Access Control tab

Stewards manage space activation, the steward user list and steward groups here, and approve or deny pending steward-access requests — the tab button carries a red count badge while requests wait.

The Access Control tab button shows a red pill with the number of pending steward requests whenever there are any (the count is pre-fetched at load so the badge appears immediately). The tab holds three cards: Space Activation, Stewards, and Pending Access Requests, plus the footer note "Note: Space Stewards and Confluence Administrators always have these privileges."

Space Activation (a custom dropdown, stored as activation)

The Stewards card

"Stewards can view all sealed attachments in this space and force-unseal them if needed. Space admins and organization admins are stewards automatically." Named stewards render as avatar mini-cards with a remove (×) button; an Add Steward card opens a user search (initial list of 10, infinite scroll, live search from 2 characters). Below it, the Groups section ("Members of these Confluence groups are automatically granted steward access to this space.") manages group chips with an + Add Group search. The lists persist as adminUsers and adminGroups on admin-settings-space-{key} when you press Apply Configuration.

What Approve and Deny actually do (Pending Access Requests)

1. 1Approve calls approve-steward-request: the backend re-verifies the CALLER is a steward, appends the requester ({accountId, displayName}) to the space's adminUsers list, deletes the request record, and the console shows "Steward access granted." and refreshes the Stewards grid.
2. 2Deny calls deny-steward-request: the request record is kept and stamped status "denied" + deniedAt, which starts the requester's 48-hour cooldown; the console shows "Request denied."
3. 3Both actions are steward-gated server-side with isOperatorSteward — independent of the force-unseal toggle, so a steward can manage requests even when force-unseal is disabled site-wide.

66Space console: Seal Duration, Macro, Validations and Workflow tabs

The remaining steward tabs override the global seal duration for this space, control macro auto-insert placement, and host the space-scope validation and document-workflow editors.

Seal Duration

One checkbox — Use System Default Seal Duration — and, when unchecked, a Custom Seal Duration hours input (pre-filled with 48 the moment you uncheck). The row's own description spells out the effect: "Seals on attachments in this space will expire after N hours. This overrides the global default seal duration for this space only." The value is stored as autoUnlockTimeoutHours; null means inherit.

Macro

Auto-Insert Macro — "Sentinel Vault automatically adds its macro to a page in this space the first time an attachment is sealed... This can be overridden on individual pages." — and, nested under it (greyed out when auto-insert is off), Macro Position with Top / Bottom radio buttons. The position hint is honest about a limitation: "To move an already-inserted macro, edit the page in the Confluence editor." Note the layered gate: the space toggle only matters while the global Auto-Insert Macro on Seal switch is on — the global switch off means no auto-insertion anywhere, regardless of space settings.

Validations

Renders the shared validations editor at space scope — the same component the site-wide console uses at global scope, covering content rules, enforcement modes and the Semantic AI configuration. Space rules, modes and AI settings override the global ones when present. The rules themselves are documented in the Validations part of this manual.

Workflow

Two stacked panels: a read-only workflow dashboard (state distribution counts, an overdue count for Approved pages whose review-due date has passed, and a most-recently-changed table capped at 100 rows — counts are exact even when the table truncates) and the workflow settings editor: "Enable document workflow", "Auto-start workflow on new pages", the read-only "Workflow states" preview, "Require approval to reach Approved" with an approver picker (people and groups), a "Decision rule" ("Any one approver can approve" / "All approvers must approve" / "At least a set number must approve" with a "Minimum approvals" count), and the non-approved edit policy: "Move it back to Draft (keeps their edit)" or "Revert to the approved version (discards their edit)".

67Site-wide console: the General tab

Every global default lives here — seal duration, the force-unseal master switch, expiry-notification mode, the three destructive-action toggles, page-body protection, and macro auto-insert.

General tab settings (label → stored KVS field on admin-settings-global)

There is one presentation-protection flag with no UI row: enforceMediaPresentation. It defaults ON (!== false) and makes sealing an image also seal how it presents on the page — layout, width, width type and pixel dimensions. Only seals created after the feature shipped carry a presentation baseline; older seals are skipped rather than guessed at. Setting the flag to false in admin-settings-global is the explicit opt-out.

68Site-wide console: the Alerts tab

Seven toggles control every notification surface; the master switch for comment-with-mention notices gates the three sub-toggles nested under it.

The Alerts tab is the notification control panel. Four top-level toggles — Enable Pop-up Notifications (toasts on seal/unseal/violation), Enable Page Status Banners (the ribbon at the top of pages with sealed attachments), Enable Page Comments (a Confluence comment posted on seal/unseal/violation), and Enable Native Notifications — plus three sub-toggles that only render while Native Notifications is on: Seal Confirmation & Halfway Reminder Notices, Seal Expiry Notices, and Recurring Reminder Banners.

The master switch's own description explains the mechanism: "Notify users by posting a Confluence comment that @mentions them. Confluence's own notification engine then emails the user according to their personal notification settings. This is the master switch — it must be on for any of the options below to work." There is no email service anywhere in the app — zero egress is a product commitment — so "email" always means Confluence's native mention email.

69The permission model: who is a steward, and what force-unseal does

Steward is a resolved role (site admin, space admin, listed user, or group member), destructive actions are double-gated by a toggle plus that role, and a force-unseal tears down the seal's entire state.

The roles

Seal owner

The user who sealed the file (lockedBy on the seal record). Owners edit their own sealed content freely — an owner's edit, removal, or trash of their own file re-baselines or releases the seal rather than fighting it. Owners approve/deny edit requests for their files.

Steward

Resolved per space by isOperatorSteward, true if ANY of: the user is a Confluence site/org admin (an 'administer' operation with target 'application'); the user holds the space's ADMINISTER permission (space admin); the user is in the space's — or, as fallback, the global — adminUsers list; the user belongs to one of the configured adminGroups. Stewards see the full space console, manage access requests, and can approve edit requests for any seal in their space.

Steward with override

authorizeSteward = the global Allow Steward Force-Unseal toggle (allowAdminOverride) AND isOperatorSteward. This is the gate on force-unseal, workflow-steward actions and other override paths. Toggle off = no steward, however senior, can force-unseal.

Edit grantee

A user holding an approved edit grant on one specific sealed file (or sealed section). The grant is a KVS record whose TTL equals the seal's expiry; the grantee's edits become the new sealed baseline. Revoking or unsealing sweeps the grant.

Site admin

Always a steward of every space, and additionally the only role that can edit the GLOBAL workflow definition and open the site-wide console.

Double gating

Destructive actions require the feature toggle AND per-actor authorization — either alone is not enough. Deleting from the panel requires allowArtifactDelete on AND refuses any file sealed by another user. Purging requires allowSealPurge on AND owner-or-steward — unconditionally, even when no seal record exists (a closed hole: the toggle alone once let any user purge any attachment by id). Force-unseal requires allowAdminOverride on AND steward status.

What Force Unseal actually cleans up (steward-unseal)

1. 1Deletes the protection-{attachmentId} seal record — then re-reads it to CONFIRM the delete landed before claiming success ("Seal removal could not be confirmed" otherwise).
2. 2Touches the protections-last-modified stamp so every open page's 5-second poll and the hourly index cron see the change.
3. 3Removes the protection- content property from the page (the trigger fast-path probe).
4. 4Deletes the space-protection-{spaceId}-{attachmentId} index row so the Sealed Files tab drops it.
5. 5Deletes all pending watch-release notification keys for the file, then sweeps every edit request and grant tied to the seal.
6. 6Notifies watchers that the file was released, and posts a comment @mentioning the seal owner that a steward force-unsealed their file, naming the steward and the time.

70Notification channels and which toggle gates each

Five delivery surfaces — footer comments with @mentions, page banners, toasts, watch releases, and the expiry/halfway reminders — each sit behind a specific Alerts-tab toggle.

Every channel, its trigger, and its gate (resolved by shared/bulletin-flags.js)

Violation-comment dedup: why you get one comment, not five

Violation comments are deduplicated per (page, attachment/section, class) for 24 hours (VIOLATION_NOTICE_TTL_MS = 24 * 3600 * 1000). The deduplicated classes are content-loss, revert-failed, layout-changed, section-removed and section-edited — and a UI delete of an embedded attachment, which fires both a delete event and a content-removal on the page pass, aliases to the single shared content-loss class so one delete produces one comment, not two. A clean save (a run that saw no violations at all) clears the markers early, so the NEXT tamper comments immediately rather than waiting out the window.

71How the app runs: triggers, schedules, queues and the write pipeline

Real-time page and attachment triggers do the enforcement, four hourly/daily scheduled jobs and two queue consumers do the heavy lifting, and every page mutation goes through a single-write, 409-retried pipeline.

Background machinery (manifest.yml)

The single-write pipeline

On every page save the trigger does ONE body read, then ordered in-memory passes — workflow enforcement first (which short-circuits the rest when it reverts the whole page), then sealed sections, then sealed media — and ONE write. The write is version-checked: a 409 conflict (a human saved concurrently) is retried up to 3 times with exponential backoff (2^attempt * 500 ms), and if every attempt loses, the app stops WITHOUT claiming success — notifications are dispatched only after a confirmed write, so it never tells an owner "restored" about a restore that did not land.

Loop safety and at-least-once delivery

Every restorative write is made as the app, and both product triggers compare the event actor against the cached app account id (app-account-id) and return immediately on a match — otherwise each restore would re-fire the trigger forever. Confluence events are at-least-once, so everything user-visible is idempotent: validation dedups per (page, version), expiry and halfway notices dedup per seal, and violation comments dedup by class for 24 h. If the app's own account id cannot be resolved, the page trigger fails CLOSED — it skips body-mutating work rather than risk a revert loop.

72Licensing: Paid via Atlassian, and what a lapsed license does (and doesn't) do

Billing runs entirely through the Atlassian Marketplace, the app is free for sites of up to 10 users, and a lapsed license soft-degrades to a banner — protection never stops.

Sentinel Vault is licensed Paid via Atlassian (app.licensing.enabled: true in the manifest): Atlassian Marketplace handles the subscription, the invoice and the enforcement of payment. The app is free for sites with up to 10 users; above that, pricing is a low per-user subscription set on the Marketplace listing — there is no in-app payment surface of any kind.

The soft-degrade principle

A lapsed license never stops protection. Sealed files keep reverting unauthorized edits, sealed sections keep restoring, validations keep running, notifications keep posting. The only in-app consequence is a banner on the two admin consoles. This is a deliberate product rule for a content-protection app: hard-blocking on a billing lapse would mean the app un-protects the very content users trusted it with.

The banner

When — and only when — the platform explicitly reports the license as inactive, both consoles show an amber banner directly under the header: "Sentinel Vault is unlicensed. Your sealed content stays protected — please renew your subscription to keep using the app." with a Manage subscription button that opens Confluence's app management (Universal Plugin Manager). The check is check-license reading context.license.active with a fail-open bias (active !== false): an absent or undefined license — which is what development and free-tier installs report — reads as licensed, so the banner can never nag a site that owes nothing.

73Limits & numbers

Every hard number in the product — upload caps, scan bounds, retry budgets, dedup windows and cooldowns — in one table.

The numbers that govern behavior

74Troubleshooting

The most common 'why did it do that' questions — missing violation comments, Trash badges, reverted resizes, absent buttons, and what uninstall destroys.

Why is there no violation comment for this tamper?

Two candidates, in order of likelihood. (1) Dedup: the same class of violation on the same page/attachment already commented within the last 24 hours, and no clean save has happened since — the revert still ran (check the page version history for the app's restore version), only the comment was suppressed. (2) Toggles: violation comments need BOTH "Enable Page Comments" AND "Enable Native Notifications" on in the Alerts tab; either off silently skips the comment (and deliberately does not consume the dedup window).

Why does the space console show "Trash" on a sealed file?

The seal record is alive but the attachment currently sits in Confluence's trash — typically the owner trashed it from Confluence's own UI, or a restore is pending. The seal is kept on purpose so the file stays recoverable and listed. Restore the file from trash (or via the panel's restore action when "Allow Attachment Restore from Page" is enabled) and the badge returns to Sealed. A "Missing" badge means the file is permanently gone; enable "Allow Seal Cleanup from Page" to purge the leftover record.

Why did my image resize revert?

The image is sealed and presentation enforcement is on (the default): a seal on an embedded image also covers its on-page presentation — layout, width, width type and dimensions — so a non-owner's resize or layout change is reverted to the sealed presentation, with one deduplicated comment. Only seals created since the presentation feature shipped carry a baseline; older seals never revert presentation. The owner (or an approved edit grantee) can resize freely — their change becomes the new baseline.

Why can't I see the steward tabs / the Force Unseal button?

Tabs: you are not resolving as a steward of this space — you need site/org admin, space ADMINISTER, a spot in the space's (or global) steward user list, or membership in a configured steward group. Button only: stewardship is fine but the global "Allow Steward Force-Unseal" toggle is off; the console checks it on load and hides Force Unseal for everyone.

Why can't a user re-request steward access?

A denied request starts a 48-hour cooldown. The console shows the remaining time on the denial banner; after it elapses, the denied record is cleared the next time the user opens the console and the request banner returns.

What happens on uninstall?

The lifecycle trigger enumerates and deletes ALL app storage — every seal record, section snapshot, edit grant, validation finding, workflow log and setting — cursor-paginated at 250 keys per page up to a 100,000-key backstop. Attachments, pages and comments the app posted are Confluence content and are untouched. A reinstall starts from a completely empty state: nothing is sealed, all settings return to defaults.