@knpkv/control-center 0.4.0 → 0.5.0

package/README.md

@@ -461,13 +461,19 @@ The issue-targeted proposals are useful for review and authorization workflows,
 
 The production Confluence adapter negotiates `entity.read@1`, bounded `sync.incremental@1` for the `pages` stream, and governed `action.propose@1`, `action.execute@1`, and `action.reconcile@1` page publication. Each connection is pinned to one immutable space ID under its verified Atlassian site. Space iteration and actions always send that exact ID to Confluence and reject any returned page belonging to another space, so followed spaces sharing one OAuth site remain isolated.
 
-Synchronization retains current page and bounded revision metadata, owner/author/contributor/watcher roles, and at most two pages each of watcher and attachment metadata without loading attachment bytes. Page bodies remain `contentState: "lazy"`; `entity.read` loads and safely converts ADF only when the page is opened. Titles containing operational runbook terms emit explicit `confluence.runbook-candidate` evidence rather than silently classifying a page as authoritative documentation.
+Synchronization retains current page and bounded revision metadata, owner/author/contributor/watcher roles, safely converted current page text, and at most two pages each of watcher and attachment metadata without loading attachment bytes. When the normalized payload would exceed its bound, content is dropped first and explicitly remains `contentState: "lazy"`; `entity.read` can still load and safely convert the exact page. Titles containing operational runbook terms emit explicit `confluence.runbook-candidate` evidence rather than silently classifying a page as authoritative documentation.
 
 One invocation reads at most five provider pages and persists a resumable `bounded:<cursor>` checkpoint when more work exists. Large provider pages are deterministically divided into contract-sized atomic pages. Intermediate chunks use a restart checkpoint for the current provider page so interruption replays stable event identities instead of skipping uncommitted entities.
 
-An `update-page` proposal accepts bounded Markdown, converts it through the owning package's strict outgoing ADF validator, and freezes the canonical ADF, title, space, expected version, and exact next version in the authorized payload. Final preflight blocks a changed revision or a visible unpublished draft before dispatch, and dispatch checks for a draft again immediately before mutation. The provider update then supplies only `expectedVersion + 1`, so Confluence's atomic version check prevents a superseded authorization from overwriting newer published content. The draft probes are defense in depth rather than an atomic guarantee: Confluence exposes no conditional update that prevents a draft created after the final probe from being merged or overwritten, so callers that require draft-atomic publication must not use this action. Each published version carries a bounded Control Center idempotency-and-payload marker. A timeout, conflict, outage, or malformed post-write response becomes an unknown outcome, while a provider-declared invalid request is a confirmed rejection. Reconciliation reads the exact authorized version for that marker without replaying the mutation, so recovery can find it after arbitrarily many later edits. Because Confluence uses the same exact-version 404 for an absent version, a vanished page, and lost permission, and may omit version messages, those ambiguous observations remain pending instead of producing a false terminal failure. The retained marker keeps historical publication evidence attributable after later edits. Cancellation remains unsupported because the provider update is synchronous.
+An `update-page` proposal accepts bounded Markdown, converts it through the owning package's strict outgoing ADF validator, and freezes the canonical ADF, title, space, expected version, and exact next version in the authorized payload. Final preflight blocks a changed revision or a visible unpublished draft unless the draft exactly matches the published title, ADF body, parent, and owner; dispatch repeats that equivalence check immediately before mutation. Missing comparison fields are treated as divergent. The provider update then supplies only `expectedVersion + 1`, so Confluence's atomic version check prevents a superseded authorization from overwriting newer published content. The draft probes are defense in depth rather than an atomic guarantee: Confluence exposes no conditional update that prevents a draft created after the final probe from being merged or overwritten, and newly editable provider fields require explicit equivalence coverage, so callers that require draft-atomic publication must not use this action. Each published version persists the exact marker `Control Center <authorized idempotencyKey> <payloadDigest>[ · <bounded versionMessage>]` in its Confluence version message. The durable provider outcome separately records either the terminal provider-operation identity `confluence-page:<pageId>:v<targetVersion>` or, while an outcome is unknown, the reconciliation key `cfpg:v1:<pageId>:<targetVersion>`; neither is folded into the version marker. The normalized `pluginConnectionId` is an authenticated client-visible identifier used in typed HTTP route parameters and the browser's cross-tab synchronization storage key; it is not a credential or raw provider locator and must not cross an unauthenticated or public boundary. The verified Atlassian `siteId`, API credentials, and raw provider secrets remain server-private. None of those values are marker fields or canonical payload fields. A timeout, conflict, outage, or malformed post-write response becomes an unknown outcome, while a provider-declared invalid request is a confirmed rejection. Reconciliation reads the exact authorized version for that marker without replaying the mutation, so recovery can find it after arbitrarily many later edits. Because Confluence uses the same exact-version 404 for an absent version, a vanished page, and lost permission, and may omit version messages, those ambiguous observations remain pending instead of producing a false terminal failure. The retained marker keeps historical publication evidence attributable after later edits. Cancellation remains unsupported because the provider update is synchronous.
 
-Unbounded watcher/activity history, authoritative deletion evidence, scheduled or webhook synchronization, and content search remain deferred to later Confluence milestones.
+The canonical item page presents synchronized safe Markdown as an in-place visual editor for workspace owners. Saving always targets the exact normalized page and revision; Relay can draft against that same page before the owner confirms publication. Markdown task checkboxes on pages related directly to a release are counted in the release workset. A task-only update is enabled only when the normalized page explicitly proves that its Markdown can replace the provider ADF without losing structure; ordinary safe projections remain read-only because they deliberately omit destinations, media, raw HTML, and ADF round-trip metadata. Unchecked tasks, lazy page bodies, a truncated release graph, or an affected CodePipeline execution that is not waiting at an observed approval stage block a new Jira release-version publication. Every pipeline reached by a current pull-request `delivered-by` relationship is affected; each must expose a manual approval action or an approval-named stage and keep that stage running while the release is prepared.
+
+While an enabled Confluence page is open and visible to a workspace owner, the browser performs one immediate connection-wide synchronization and repeats it every 15 seconds; saving or manually requesting a refresh can trigger an additional synchronization after current work settles. Same-origin browser tabs and mounted page controllers for the same connection share one foreground cadence. This foreground, owner-visible refresh is distinct from background scheduling: unbounded scheduled synchronization and webhook-driven synchronization remain deferred.
+
+Confluence release templates are synchronized pages whose title contains the word `template`. Classification happens before the bounded 50-template hydration limit, so unrelated pages cannot hide a later template. The release agent loads only classified pages with exact readable content, places a copy in the release editor, and creates a separate Confluence page while the source remains unchanged. The durable canonical request is the governed-action `envelope_json`; its `releasePublication` structure persists the release ID, predecessor publication action, optional `templateSourceEntityId`, source-revision digest, and source-revision count. The publication idempotency digest binds workspace, release, provider and action kind, title, Markdown, parent, predecessor, source entity, Confluence page and expected version, source-revision digest, destination, and target entity. Provider credentials and private locators remain server-private and are never canonical payload fields.
+
+Unbounded watcher/activity history, authoritative deletion evidence, background scheduled or webhook synchronization, and content search remain deferred to later Confluence milestones.
 
 ### Clockify time-entry integration
 
@@ -503,7 +509,7 @@ Secure blob reads and publication require the host to expose opened files and di
 
 ## Local authentication
 
-`Auth` uses ten-minute, single-use pairing codes to create browser sessions. The first code for a workspace is unique and creates its owner; further device codes, session listing, and targeted revocation require an active owner session. Sessions have a twelve-hour sliding idle limit, a thirty-day absolute limit, and a separate CSRF credential for mutations. SQLite contains only SHA-256 credential digests. Invalid, expired, replayed, revoked, and malformed stored credentials share the same public rejection shape.
+`Auth` uses ten-minute, single-use pairing codes to create browser sessions. The first code for a workspace is unique and creates its owner. An owner can use the **Browsers** section in workspace settings to add further owner or approver browsers, inspect every independent session, and revoke a selected browser without disrupting the current one. The displayed device code is returned once with `private, no-store` response policy and is never persisted by the browser. Sessions have a twelve-hour sliding idle limit, a thirty-day absolute limit, and a separate CSRF credential for mutations. SQLite contains only SHA-256 credential digests. Invalid, expired, replayed, revoked, and malformed stored credentials share the same public rejection shape.
 
 Use `authLayer(persistenceConfig)` from `@knpkv/control-center/server` for standalone composition. `TerminalRecovery` is a separate, terminal-only service: it derives the exact canonical `0700` directory from the configured database, requires an exact confirmation phrase, and proves that the running process owns the descriptor-pinned directory before it can issue an owner recovery code. Each successful recovery creates a durable audit event. Recovery is deliberately absent from the HTTP-facing `Auth` service.
 
@@ -553,10 +559,14 @@ the normalized provider identities and account/resource bindings. Scope finaliza
 server and removes the database, blob, static, and secret roots after success, failure, timeout, or
 interruption. The scheduled/manual workflow builds a checksum-sealed runner in a job without OIDC,
 then verifies it in the protected `control-center-live-integration` execution job before assuming the
-AWS role. The short-lived runner artifact contains code and dependencies only; provider credentials,
-results, logs, and runtime evidence are never uploaded. Ordinary pull-request tests never select
-this entry. The external read-only AWS role and stable provider fixtures are defined in
-`infra/control-center-live-aws`; interactive Atlassian OAuth consent remains tracked by #242.
+AWS role. That GitHub environment is the non-mutable trust boundary for manual `workflow_dispatch
+--ref` runs: keep its deployment branch policy limited to `main`, store the Atlassian secrets only in
+that environment, and pin the AWS role trust policy to the repository and environment OIDC subject.
+A branch-authored workflow-level `if` is only defense in depth because a selected ref can change its
+own YAML. The short-lived runner artifact contains code and dependencies only; provider
+credentials, results, logs, and runtime evidence are never uploaded. Ordinary pull-request tests
+never select this entry. The external read-only AWS role and stable provider fixtures are defined in
+`infra/control-center-live-aws`; interactive Atlassian OAuth consent remains tracked by issue `#242`.
 
 The smaller AWS-only acceptance command is
 `pnpm --filter @knpkv/control-center test:integration:live-aws`. It requires