Issues, comments, labels, milestones

S21 ships the issues subsystem: issues + threaded comments, labels, milestones, the polymorphic timeline event log, and the cross-reference index. The same tables are reused by S22 for pull requests via the issue_kind discriminator.

Schema (migration 0022)

repo_issue_counter   — per-repo monotonic numbering (issues + PRs share)
issues               — the row; kind discriminator covers PR rows in S22
issue_comments       — per-issue threaded comments
issue_assignees      — many-to-many issue ↔ user
labels               — repo-scoped labels
issue_labels         — many-to-many issue ↔ label
milestones           — repo-scoped milestones
issue_events         — generic timeline events (closed, locked, labeled, …)
issue_references     — cross-reference index (comment / issue / commit → issue)

The kind column on issues is in from day one ('issue' | 'pr') so S22's PR rows are first-class without a schema split. PR-specific fields land in a pull_requests table keyed on issues.id.

Per-repo numbering

repo_issue_counter (repo_id, next_number) is allocated lazily at first issue creation and on every repo create (S16's repos.Create calls EnsureRepoIssueCounter inside the create tx). Allocation is one UPDATE … RETURNING inside the same tx as the issue insert:

UPDATE repo_issue_counter
SET next_number = next_number + 1
WHERE repo_id = $1
RETURNING (next_number - 1)::bigint AS allocated;

Postgres serializes concurrent updaters on the row lock, so concurrent issues.Create calls on the same repo end up with distinct numbers. The race test (TestCreate_ConcurrentRaceForUniqueNumbers) fans out 8 goroutines and asserts no duplicates.

Default labels

Repo create seeds the GitHub-aligned set:

bug · d73a4a · Something isn't working
documentation · 0075ca · Improvements or additions to documentation
duplicate · cfd3d7 · This issue or pull request already exists
enhancement · a2eeef · New feature or request
good first issue · 7057ff · Good for newcomers
help wanted · 008672 · Extra attention is needed
invalid · e4e669 · This doesn't seem right
question · d876e3 · Further information is requested
wontfix · ffffff · This will not be worked on

Seeding runs inside the repo-create transaction via issues.SeedDefaultLabels(ctx, tx, repoID). It swallows unique-violations so re-runs are no-ops; backfill for repos created before S21 is a one-off SQL INSERT … ON CONFLICT DO NOTHING.

Routes

Public reads still pass through policy.Can(ActionIssueRead) so private repos return the existence-leak 404. RequireUser on writes gives anonymous browsers a /login redirect instead of the same 404. Issue creation and commenting follow GitHub's public-participation model: any logged-in user may open or comment on issues in a public repo, while private repos require read access.

The issue page is capability-driven:

• The comment box appears only when policy.Can(issue:comment) allows and the issue is not locked, unless the viewer is triage+.
• Close/reopen appears for triage+ users and for the issue author.
• Labels, assignees, milestones, and lock controls appear only for the matching triage-level policy action. Public participants should not see forms that only lead to 403s.

Cross-reference indexing

internal/issues/references.go::insertReferencesFromBody parses #N and owner/repo#N from the comment / issue body inside the creating transaction. Each parsed reference produces:

1. an issue_references row pointing source → target,
2. a referenced event emitted on the target issue's timeline.

The cross-repo regex runs first; matched ranges are stripped before the same-repo regex sweeps so alice/proj#3 doesn't also trip the #3 matcher. Self-references skip silently. Unknown owners / repos / issue numbers are best-effort dropped — malformed references shouldn't fail the create.

Commit-message references (S14's push:process) call into the same helper with srcKind = "commit_message" and srcObjectID = push_event_id once that worker job ships.

Markdown + sanitization

Issue bodies and comments use the existing S17 markdown pipeline (internal/repos/markdown.RenderHTML): Goldmark for parsing, bluemonday's UGCPolicy for sanitization. Rendered HTML is cached on body_html_cached; md_pipeline_version lets the worker re-render on pipeline upgrades (post-MVP).

<script> tags are stripped — the sanitization test (TestCreate_RendersHTMLAndSanitizesScripts) injects one and asserts the cached HTML doesn't contain <script while still rendering **bold** as <strong>bold</strong>.

Locked issues

SetLock flips locked + emits a locked/unlocked event. Comments hit the locked gate inside AddComment: non-collaborators get ErrIssueLocked. The IsCollab flag is the caller's responsibility; the web handler resolves it via policy.HasRoleAtLeast(..., RoleTriage), so owners, direct collaborators, and team-derived triage+ roles can comment through a lock.

Rate limit

Comment creation hits the existing throttle bucket (scope=issue_comment, identifier=user:N) at 20 per hour. Issue creation isn't independently rate-limited; the broader repo_create bucket and account anti-abuse measures cover the spam-floor case for now.

Timeline events

issue_events is intentionally polymorphic: kind is a free string, meta is a jsonb blob, and ref_target_id is a denormalized pointer for events that target another issue (referenced, marked_as_duplicate_of, etc.). Known kinds today:

closed, reopened, locked, unlocked,
labeled, unlabeled,
assigned, unassigned,
milestoned, demilestoned,
referenced

meta always carries an empty '{}'::jsonb when no metadata is applicable — Go's nil byte slice would bind as SQL NULL and trip the NOT NULL constraint, so the orchestrator passes []byte("{}") explicitly.

Tests

Deferred

• Mention notifications — extractMentions is in place, but the notifications surface (S29-area) hasn't shipped, so parsed @username tokens currently don't emit anything.
• Commit-message references — the helper accepts srcKind = "commit_message" already; wiring lives with S14's worker job (push:process).
• Cross-org references — the cross-repo regex resolves only user-owned repos; org owners arrive in S31.
• Required signing / status checks on comments — out of scope.
• Reactions, edit history, comment edits across users — post-MVP UI polish (S30+).
• Server-side label / assignee / milestone filtering — current list query filters by state + kind only; richer filtering is the perf-pass item in S36.
• Issue templates / forms — post-MVP.
• Reactions — post-MVP (own table; doesn't touch the schema here).