Add tech specs for Workflow Runs visibility and attribution

[issuetopr-dev]

This PR adds a new technical specifications document derived from docs/internal/PRD.md.

What’s included

• New doc: docs/internal/workflow-runs-tech-specs.md
• Clearly enumerates the shape of new/updated functions, interfaces, and files needed to implement v1 of Workflow Runs visibility and attribution.
• No implementation details — only filenames, exported members, and input/output shapes as requested.

Highlights

• Shared ports and adapters: DatabaseStorage, WorkflowRunsRepository, CreateWorkflowRunInput, WorkflowEventInput, etc.
• Next.js surfaces: GET routes and page helpers with return types.
• Workers integration touchpoints for run creation and event appends.
• Back-compat section listing current lib/neo4j/services/workflow.ts APIs (signatures only).

Linting

• ESLint passes (pnpm run lint). Prettier/tsc checks are not enforced in CI and would fail on unrelated legacy files, so changes are limited to documentation only.

Please review the function and file shapes. Implementation can follow in subsequent PRs.

Closes #1428

---

Update: Addressed review feedback to consolidate attribution fields into an actor object.

• Changed in docs/internal/workflow-runs-tech-specs.md:

  • CreateWorkflowRunInput: replaced individual initiator/trigger fields with a discriminated union actor:
    • { kind: "user"; userId: string; github?: { id?: string; login?: string } }
    • { kind: "webhook"; source: "github"; event?: "issues.labeled" | "pull_request.labeled" | "unknown"; installationId?: string; sender?: { id?: string; login?: string } }
    • { kind: "system"; reason?: string }
  • ListedWorkflowRun: now exposes the same actor shape instead of separate initiator*/installationId fields.
  • Notes added to clarify that Requester can be derived from actor for authorization and that installationId is also accessible via actor when kind=="webhook".

• Rationale: Keeps attribution cohesive and extensible across UI, API, and workers while matching the suggestion in review.

• Review comment addressed: Add tech specs for Workflow Runs visibility and attribution #1429 (comment)

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[youngchingjui]

I think this generally looks OK? I couldn't look at all of it. the formatting in this diff editor is hard to read. Let's just make the change I asked for in the review comment.

[youngchingjui]

I think this could be combined into an actor object that might be a discriminated union of different actors, including the user, webhook, etc.

[cursor]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on January 19.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.