GV-10: Visibility-gated events, webhooks, notifications, queues, reviews, work items, and artifacts

[ScottArbeit]

GV-10: Visibility-gated events, webhooks, notifications, queues, reviews, work items, and artifacts

Parent epic: #638

Plan ID: IMP-10

Depends on: #645

Branch Contract

• Top-level integration branch: epic/638-visibility-owned-branches.
• Start only after accepted-private PromotionSet workflow is available on the epic branch.

Objective

Gate public-facing event and workflow projections so private branch/reference/promotion activity does not leak through webhooks, SignalR/watch, notifications, queues, review reports, work items, artifacts, or search/activity surfaces.

Why This Matters

Visibility bugs often hide in projections outside the main read route. Accepted-private work must not leak through event names, delivery ids, review queues, or linked artifacts.

Minimum Detail Gate

• Invariant tuple: Internal persisted actor events may remain complete, but every external projection/delivery is computed for a caller or subscription audience and suppresses private resources until reveal.
• Forbidden implementation shapes: Do not send promotion-set.applied for private apply to public webhook owners. Do not expose private ids in webhook delivery records, user-facing logs, queue candidates, review artifacts, or work-item links. Do not rely only on internal event persistence suppression; projections need audience filters.
• Positive tests: Authorized audience receives private signals according to explicit audience rules.
• Negative tests: Public webhook delivery count is unchanged for private create/apply; public notification/watch observes no private activity.
• Regression tests: Existing public webhook/event flows continue for public resources.
• Boundary/property tests: Reveal emits exactly one public event/projection and does not replay private history. For public subscribers, projected event stream equals filtering internal stream to visible resources plus reveal events.

Candidate Owned Paths

• src/Grace.Server/WebhookDispatch.Server.fs
• src/Grace.Types/Webhooks.Types.fs if event names/versioning change.
• Notification/SignalR/watch server modules.
• Queue/review/work-item/artifact route modules.
• src/Grace.Server.Tests/* webhook/projection/review tests.
• src/Grace.CLI.Tests/* watch tests if watch is affected.

Implementation Seams

• Add audience-aware event projection and dispatch filters.
• Define reveal-time public event semantics and event name/version if product needs webhooks.
• Filter queue/review/work-item/artifact links pointing to private refs/promotion sets.
• Gate notifications/watch/SignalR groups by visible branch/reference audience.

Contract Propagation

• Events, webhooks, SignalR, watch, search, and projections: update with projection tests.
• Review/queue/work-item/artifact route outputs: update if present/touched; otherwise provide source-search waiver.
• Docs/event reference: defer to GV-15 unless event names change.

Stale-Authority Preflight

• Authoritative state: persisted actor event plus current resource visibility/audience at projection time.
• Revalidate before dispatch/delivery/public projection, not only when the event was originally emitted.
• If reveal projection fails after reveal event, retry must be idempotent and must not duplicate public webhooks.

Validation

Server-api plus async/runtime plus event projection profile. Run focused webhook/notification/work-item tests, targeted Fantomas, and Fast or Full if Service Bus/SignalR/Aspire participates.

Product Decisions Covered

PD-01, PD-02, PD-03, PD-08.

Acceptance Criteria

• Public event/webhook/notification projections are silent before reveal.
• Authorized private audience receives intended signals.
• Reveal-time public event semantics are proven.

Approved Carry-Forward Decisions And Proof Obligations

These decisions are already approved through the #645 unblock and review-stabilization work. Treat them as part of this issue's contract, not as optional implementation notes.

• Reveal is the first public publication point for private accepted PromotionSet work. A terminal reveal must create the public promotion_set.applied webhook delivery and the public PromotionSetApplied automation/Eventing projection exactly once.
• Private review events and review projections created from a private PromotionSet must inherit private visibility metadata before publication. Public automation must suppress those private review events until the source becomes public through reveal.
• Queue state exposed through review candidate and review report snapshots must use the same caller-visible queue projection as the queue routes. A public candidate must not reveal hidden private running or queued work in the same branch queue.
• Queue mutations for private PromotionSets, including retry, cancel, enqueue, dequeue, and gate-rerun style operations, must stamp private visibility metadata so public automation does not receive hidden PromotionSet ids through queue events.
• Routes that load or act on a PromotionSet id must prove the caller can observe that PromotionSet before returning projections or mutating retry, cancel, recompute, enqueue, dequeue, or gate-rerun state. Hidden private PromotionSets are missing-equivalent or no-op to non-observers.
• Public-facing projection, dispatch, and delivery code must re-check the current visibility of the source at projection time. Do not rely on the visibility that was true when an internal actor event was first persisted.

Stabilization Preflight For The Worker

Before editing code, identify the exact external surfaces that currently exist for webhooks, Eventing/automation, SignalR/watch, notifications, queues, review reports, work items, artifacts, activity/search, and logs. For each surface, record one of these outcomes in the handoff:

• updated with an audience-aware projection or visibility stamp;
• proven already covered by the GV-06: PromotionSet accepted-private workflow and terminal reference secrecy #645 implementation with a source and test anchor;
• not present in the current codebase, with the search evidence;
• deferred to a named sibling issue because the surface is outside GV-10's owned contract.

The proof set must include negative evidence that a public observer cannot learn private branch, reference, PromotionSet, queue, review, work-item, artifact, or delivery ids from a projection side channel. If a new durable projection concept, retry policy, stale-source rule, or public contract is needed and it is not already named above, stop and ask for maintainer approval before implementing it.

[ScottArbeit]

Claiming this issue for the #638 orchestration pass.

Branch/worktree setup:

• Branch: agent/649-visibility-gated-projections
• Worktree: C:\Source\Grace-gh-649
• Base: origin/epic/638-visibility-owned-branches

I will route GV-10 projection visibility implementation to a fresh worker and keep GitHub coordination, review status, and merge cleanup in the orchestrator.

[ScottArbeit]

Review Stabilization Ledger - Cycle 2

PR: #695
Current head with findings: c1c51b5c120d50a6f2693e7f5c90396280bc6dcb

Review Timeline

• First substantive Codex cycle on 393ef657: three P1 findings in Notification.Server.fs around deleted reference fanout, quick-scan fanout ordering, and summary artifact PromotionSet scope. The CI run also failed in ServiceBusSubscriberDispatchesMatchingWebhookOnceAndDoesNotBlockOnOutboundFailure while waiting for promotion-set.applied delivery. Fixed by c1c51b5c with local validate -Full and PR-attached Validate passing.
• Second substantive Codex cycle on c1c51b5c: three fresh P1 findings remain in the same high-risk projection/fanout family.

Missing Invariant Family

Public fanout needs a single structural source-scope invariant:

• Every public automation, webhook, notification, quick-scan, artifact, and work-item fanout path must carry the effective source scope before the first public projection decision.
• Missing source scope is not automatically public when the event kind is derived from a branch, reference, PromotionSet, artifact, or work item that can inherit private visibility.
• A current public snapshot can allow reveal-time publication, but it must not replay older private Created or apply-history events. Reveal remains the first public publication point for private history.
• Synthetic or integration events that are intentionally public must have an explicit safe fallback path, with regression coverage, rather than relying on None as a blanket allow.

Fresh Findings To Prove

• discussion_r3551031613: non-create PromotionSet events such as apply/recompute need the PromotionSet id stamped or derived before current visibility rechecks.
• discussion_r3551031618: add-summary artifact creation events need the same PromotionSet projection scope as the later artifact-link event.
• discussion_r3551031621: private reference Created events must remain suppressed after reveal; only the reveal event may publish the public path.

Stabilization Proof Obligations

Before requesting another review, the fix must prove the source-scope invariant across the touched fanout paths, not just the three comments:

• PromotionSet event fanout: create, non-create, apply, recompute, and retry-like events either carry a PromotionSet id/source scope or are explicitly proven public-only.
• Work-item summary fanout: prompt artifact create, summary artifact create, artifact-link, and PromotionSet-link events carry the same visibility source when the request has a PromotionSet id.
• Reference fanout: private Created events remain suppressed even if the reference is later revealed; reveal remains the only public publication point for that private history.
• Derived quick-scan and validation-result fanout cannot drop inherited source scope before public automation/eventing dispatch.
• Webhook/Eventing/Notification tests include negative public-observer assertions for missing-source, hidden-source, deleted-source, and reveal-after-private-created cases.

Stabilization Decision

Continue #649 with a stabilization fix worker. This does not require a new product decision or a new durable/public contract concept; it is enforcement of the already-approved #649 visibility and reveal-publication contract.

[ScottArbeit]

Third-Cycle Stabilization Stop

Coding is stopped for #649 / PR #695 after the third substantive Codex Code Review Bot cycle on the high-risk public fanout surface.

Review Timeline

• 393ef657: first substantive Codex cycle. Findings covered deleted reference fanout, quick-scan ordering, and summary artifact PromotionSet scope. The PR-attached Validate run also failed in ServiceBusSubscriberDispatchesMatchingWebhookOnceAndDoesNotBlockOnOutboundFailure while waiting for promotion-set.applied delivery.
• c1c51b5c: second substantive Codex cycle. Findings stayed in the same source-scope family: non-create PromotionSet events needed scope before current visibility checks, add-summary artifact-create events needed PromotionSet scope, and private Created reference events needed to stay suppressed after reveal. A stabilization ledger was posted before the next worker.
• 5208291f: third substantive Codex cycle. Current fresh findings are:
  • discussion_r3551253473: deleted PromotionSets must be treated as hidden, or deletion fanout needs an explicit exception.
  • discussion_r3551253479: review finding-resolution events need PromotionSet scope before ReviewNotesUpdated fanout.
  • discussion_r3551253484: PromotionSet artifact events created with actor metadata need a narrow ActorId fallback or explicit PromotionSetId stamping.

Suspected Missing Invariant Family

The existing ledger was directionally right, but still too narrow. The broader invariant is:

• Every public fanout path must identify the current effective source before publication.
• Deleted sources are not ordinary public sources unless a specific deletion-publication event says otherwise.
• Events derived from review, artifact, work-item, queue, reference, and PromotionSet actors must not become public merely because their metadata is missing the most convenient id field.
• A fallback from actor metadata to source scope is allowed only if the event shape proves which resource family the actor represents.
• Current public visibility must not replay old private creation/apply history after reveal.

Maintainer Decisions Needed

A local unblock page has been generated at:

C:\Users\scott\AppData\Local\Temp\grace-638-orchestration\grace-649-unblock-current.html

It asks for explicit approval on:

• Whether deleted PromotionSets are hidden for ordinary public fanout.
• Whether review finding-resolution fanout must stamp or derive the owning PromotionSet id.
• Whether artifact fanout may use ActorId as PromotionSet scope when the event shape proves the artifact was created by a PromotionSet actor.
• Whether to continue GV-10: Visibility-gated events, webhooks, notifications, queues, reviews, work items, and artifacts #649 / PR GV-10: Gate public projections by current visibility #695 with a revised stabilization ledger or split the remaining closure to a sibling issue.

No further coding or fix worker will be assigned until the maintainer approves the revised issue/ledger or explicitly directs continued patching.