---
id: 11197
title: DiscussionService flat active-tier and lazy ordinal archive refactor (#11187 AC5)
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees: []
createdAt: '2026-05-11T09:18:07Z'
updatedAt: '2026-06-07T17:10:32Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11197'
author: neo-gemini-pro
commentsCount: 0
parentIssue: 11187
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-11T12:04:36Z'
---
# DiscussionService flat active-tier and lazy ordinal archive refactor (#11187 AC5)

## Context
Part of Epic #11187 Phase 1 execution. We are converging on the Option E''+S architecture for GitHub workflow data archiving: discussions need to be collapsed to a flat structure in the active tier, and use the new lazy ordinal chunking in the archive tier.

## The Problem
The current `DiscussionService` and `DiscussionSyncer` write to sparse `XXxx` directories because the type-density for discussions is very low (~68 total items). A 100-ID chunking model produces 1-5 item folders, which is a structural anti-pattern. Moreover, no formal `discussion-archive/` layer currently exists.

## The Architectural Reality
- `ai/services/github-workflow/DiscussionService.mjs` handles file operations for Discussions.
- The active tier must abandon sparse `XXxx` chunking and write directly to a flat `discussions/` directory.
- The archive tier must use the new `archivePath()` helper (AC2) pointing to the unified `archiveRoot` specified in the config (AC1). Given the current density, the helper will inherently yield a flat folder (`archive/discussions/vN.M.K/`), but the hook enables future scaling.
- `LocalFileService.mjs` currently lacks native support for discussion lookups (unlike `getIssueById`), which is now required to resolve the active vs archive tier splits.

## The Fix
Refactor `DiscussionService` to collapse active discussion paths to a flat directory. Wire the archive-write path to use the `archivePath()` helper, establishing the formal archive destination for discussions. Add `getDiscussionById` to `LocalFileService.mjs` to support querying the new dual-tier structure.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `DiscussionService` active paths | Epic #11187 | Routes to `discussions/discussion-NNNN.md` (flat) | N/A | Inline comments | Unit tests verifying flat routing |
| `DiscussionService` archive paths | Epic #11187 | Routes to `archive/discussions/vN.M.K/{flat|chunk-N}/` | N/A | Inline comments | Unit tests verifying lazy chunking |
| `LocalFileService.getDiscussionById` | Epic #11187 | Resolves flat active paths & recursive archive paths | N/A | Inline comments | Verified pathing |

## Acceptance Criteria
- [ ] Refactor active-tier discussion writes to use a flat directory structure, eliminating the sparse `XXxx` chunking.
- [ ] Implement the archive-tier write path for discussions using the new `archivePath()` helper.
- [ ] Implement `LocalFileService.getDiscussionById` to correctly resolve flat active discussions and fallback to archive resolution.

## Out of Scope
- Actually migrating existing `XXxx` discussion files to flat structure (Phase 2 AC6).
- Actually creating the historical archive for discussions (Phase 3 AC9).
- Modifying `IssueService` (AC3) or `PullRequestService` (AC4).

## Avoided Traps
- Using ordinal chunking for the active tier. Even though we are flattening it, if it ever scales, the active tier must use deterministic ID-range chunking, never insertion-order ordinals. For now, flat is correct for its density.

## Origin Session ID
Origin Session ID: 57502eb2-7f7b-4b9b-a849-49f016b08c95
Retrieval Hint: "Epic 11187 Phase 1 DiscussionService Refactor"

## Timeline

- 2026-05-11T09:18:09Z @neo-gemini-pro added the `enhancement` label
- 2026-05-11T09:18:09Z @neo-gemini-pro added the `ai` label
- 2026-05-11T09:18:09Z @neo-gemini-pro added the `architecture` label
- 2026-05-11T09:18:19Z @neo-gemini-pro added parent issue #11187
- 2026-05-11T09:20:56Z @neo-opus-ada cross-referenced by #11198
- 2026-05-11T09:49:51Z @neo-gemini-pro referenced in commit `5a2652d` - "refactor(github-workflow): refactor DiscussionSyncer to use flat active tier and unified archivePath (#11197)"
- 2026-05-11T09:51:06Z @neo-gemini-pro cross-referenced by PR #11199
- 2026-05-11T09:58:39Z @neo-opus-ada cross-referenced by #10164
- 2026-05-11T12:04:36Z @tobiu referenced in commit `c459245` - "refactor(github-workflow): use archivePath for pull requests and discussions (#11187) (#11199)

* feat(github-workflow): introduce unified archiveRoot configuration (#11189)

* feat(github-workflow): add archive path helper (#11190)

* test(ai): add archiveRoot assertions to ConfigCompleteness (#11189)

* test(config): remove trailing whitespace (#11189)

* feat(config): add archive chunking parameters (#11189)

* refactor(github-workflow): use archivePath for pull requests (#11187)

* refactor(github-workflow): refactor DiscussionSyncer to use flat active tier and unified archivePath (#11197)

---------

Co-authored-by: neo-gemini-3-1-pro <neo-gemini-3-1-pro@users.noreply.github.com>
Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-11T12:04:37Z @tobiu closed this issue
- 2026-05-13T05:43:24Z @neo-opus-ada cross-referenced by #11187
- 2026-05-13T08:10:40Z @neo-opus-ada cross-referenced by PR #11294

