Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Changelog

## [0.4.1] - 2026-11-13

### Changed

- **The sibling-facing seam is now declared, not implied.** `src/service.ts` documents the two supported surfaces: the frozen in-process `assemble()` → `AssembleReportResult.reportDir`, and the event-driven `tool/result.meta.{reportFile,manifestFile}` projection (absolute paths, sealed results only, additive-only fields, never renamed). `test/meta-contract.spec.ts` pins the projection's shape. No behavior change. Addresses #27.

## [0.4.0] - 2026-11-10

### Added
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -171,5 +171,5 @@
"url": "https://github.com/sponsors/PerryLink"
},
"pnpm": {},
"version": "0.4.0"
"version": "0.4.1"
}
18 changes: 18 additions & 0 deletions src/service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,24 @@
* (dsh-industry-research) consume `ctx.researchReport.assemble` against this
* exact text. `scripts/verify-frozen-contract.mjs` gates drift.
*
* ── Sibling-facing surfaces (both supported) ────────────────────────────────
* Two seams are contractual for out-of-tree consumers. Pick by integration
* style, not by convenience:
*
* 1. In-process: `ctx.researchReport.assemble()` returns the frozen
* `AssembleReportResult` above. `reportDir` is the sealed directory;
* `report.md` and `manifest.json` are its fixed entry files.
* 2. Event-driven: the `tool/result` event for `name === 'research_report'`
* carries `meta.reportFile` / `meta.manifestFile` — absolute, resolved paths
* of those same two artifacts, present only when the result is sealed
* (`kind === 'sealed'`). The projection is durable and replay-safe; its
* fields are additive-only and the pair is never renamed, so a consumer that
* joins `tool/call` to `tool/result` may depend on them.
*
* The meta projection exists for consumers that cannot reproduce this plugin's
* cwd resolution; consumers that call the service directly should use
* `reportDir`. Both stay stable across minor versions.
*
* @module dsh-research-report/service
*/

Expand Down
28 changes: 28 additions & 0 deletions test/meta-contract.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
/**
* The `tool/result.meta` projection is a declared sibling surface (see the
* module doc in `src/service.ts`): exactly two absolute artifact paths, present
* only for a sealed result. An out-of-tree consumer joins `tool/call` to
* `tool/result` and cannot reproduce our cwd resolution, so a silent rename
* here would break it with no CI signal on either side.
* @module dsh-research-report/test/meta-contract.spec
*/

import { describe, expect, it } from 'vitest'
import { sealedMeta } from '../src/tools/research-report.ts'
import path from 'node:path'

describe('sibling meta projection', () => {
it('exposes exactly the two absolute artifact paths, never a directory', () => {
const value = {
reportFile: path.resolve('/w/sealed/report.md'),
manifestFile: path.resolve('/w/sealed/manifest.json'),
}
const meta = sealedMeta(value as never)

expect(Object.keys(meta).sort()).toEqual(['manifestFile', 'reportFile'])
expect(path.isAbsolute(meta.reportFile)).toBe(true)
expect(path.isAbsolute(meta.manifestFile)).toBe(true)
expect(path.basename(meta.reportFile)).toBe('report.md')
expect(path.basename(meta.manifestFile)).toBe('manifest.json')
})
})
Loading