feat(observability): propagate parentTraceId on DispatchEvent — ADR-0174 SDK retirement Phase 1.4 (#178) (#225)
* test(#178): update DispatchEvent factory tests to propagate parentTraceId P1.3 test 'parentTraceId is always undefined' replaced with four P1.4 contracts: absent → undefined, string → propagated, null → undefined, non-string → undefined (defensive normalization policy). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(#178): propagate parentTraceId through DispatchEvent factory Stop ignoring the parentTraceId parameter added as a forward-compat hook in P1.3. Defensive normalization: only non-null strings are propagated; null, non-string values, and absent callers all yield undefined, keeping P1.3 behavior intact for all existing dispatch call sites. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(#178): add Hub-level parentTraceId propagation tests Four new assertions: req.parentTraceId propagates to event, absent → undefined (P1.3 regression), shared parentTraceId across multiple dispatches, and unique traceId invariant despite shared parentTraceId. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(#178): plumb parentTraceId through Hub dispatch and _notifyLogger dispatch() now reads req.parentTraceId and passes it to _notifyLogger, which forwards it to makeDispatchEvent. Backward-compatible: callers that omit parentTraceId emit events with parentTraceId: undefined, identical to P1.3 behavior. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(#178): add trace correlation end-to-end test Dispatches a root command then 3 children with parentTraceId=rootTraceId. Reads the real .gsd-trace.jsonl audit file and verifies: 4 events total, root has no parentTraceId, all children carry rootTraceId, all traceIds unique, JS filter returns exactly the 3 children given the root's traceId. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(#178): document traceId/parentTraceId in audit file Update Observability section to note that audit events now carry both traceId and parentTraceId, and explain the correlation filter pattern. Note that leaf dispatches emit parentTraceId: undefined until the Phase 2 composer wires it automatically. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(#178): add changeset for trace correlation seam Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(#178): cover invalid parentTraceId values in DispatchEvent factory Adds 9 new test cases for UUID v4 validation of parentTraceId: empty string, whitespace, non-UUID, oversized, UUID v1, missing-hyphen, extra-char (all dropped to undefined), plus UPPERCASE and lowercase v4 (both propagated). Tests are intentionally red until the implementation commit that follows. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(#178): validate parentTraceId against UUID v4 before propagation Adds UUID_V4_REGEX constant and isValidParentTraceId() helper to event.cjs. makeDispatchEvent now silently coerces any parentTraceId that fails the UUID v4 check (wrong version nibble, wrong variant, missing hyphens, oversized, empty, etc.) to undefined. No stderr warn is emitted — the factory remains pure and side-effect-free. Closes the correlation- poisoning vector identified in the Codex adversarial review of PR #225. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(#178): assert Hub silently drops invalid parentTraceId at the seam Adds two tests to hub-logger-integration.test.cjs: 1. dispatch with 'junk' parentTraceId emits event with parentTraceId===undefined. 2. The logger-failure warn path is NOT triggered — the factory coerces the bad value before onEvent is called, confirmed by zero stderr output even when a logger that would throw on non-undefined parentTraceId is installed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(#178): assert invalid parentTraceId does not poison correlation siblings Adds one test to trace-correlation.test.cjs: dispatches a root, a valid child (parentTraceId = rootTraceId), and an invalid child (parentTraceId = 'junk'). Asserts: valid child carries correct parentTraceId, invalid child has parentTraceId dropped to undefined, filtering by rootTraceId yields exactly 1 event (the valid child only), and all 3 events have unique traceIds. Uses an isolated Hub + tmpdir to avoid shared fixture interference. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(#178): document UUID v4 contract for parentTraceId Appends one sentence to the Observability audit-trail paragraph in CONFIGURATION.md: parentTraceId must be canonical UUID v4 (RFC 4122); values that don't match are silently dropped from audit output. No section restructuring — single sentence addition only. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -44,14 +44,53 @@ describe('makeDispatchEvent — shape', () => {
|
||||
assert.notEqual(a.traceId, b.traceId, 'consecutive calls must produce different traceIds');
|
||||
});
|
||||
|
||||
test('parentTraceId is always undefined in P1.3', () => {
|
||||
test('parentTraceId is undefined when not provided (default, backward-compat with P1.3)', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: 'should-be-ignored',
|
||||
});
|
||||
// P1.3: parentTraceId field exists but is always undefined
|
||||
assert.strictEqual(event.parentTraceId, undefined, 'parentTraceId must be undefined in P1.3');
|
||||
// P1.4: when no parentTraceId supplied, field is still undefined
|
||||
assert.strictEqual(event.parentTraceId, undefined, 'parentTraceId must be undefined when not provided');
|
||||
});
|
||||
|
||||
test('parentTraceId propagates when provided as a string (P1.4)', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
|
||||
'parentTraceId must be propagated when provided as a string');
|
||||
});
|
||||
|
||||
test('parentTraceId is undefined when null is passed (defensive normalization)', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: null,
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'null parentTraceId must be normalised to undefined');
|
||||
});
|
||||
|
||||
test('non-string parentTraceId is set to undefined for defensive safety', () => {
|
||||
// Style choice: surrounding code uses undefined for absent/invalid optional fields
|
||||
// (e.g. args is omitted rather than coerced). Consistent policy: non-string → undefined.
|
||||
const eventNum = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: 42,
|
||||
});
|
||||
assert.strictEqual(eventNum.parentTraceId, undefined,
|
||||
'number parentTraceId must be normalised to undefined');
|
||||
|
||||
const eventObj = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: { id: 'x' },
|
||||
});
|
||||
assert.strictEqual(eventObj.parentTraceId, undefined,
|
||||
'object parentTraceId must be normalised to undefined');
|
||||
});
|
||||
|
||||
test('command is set from input', () => {
|
||||
@@ -116,6 +155,107 @@ describe('makeDispatchEvent — args field', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('makeDispatchEvent — parentTraceId UUID v4 validation', () => {
|
||||
const { randomUUID } = require('crypto');
|
||||
|
||||
test('invalid empty string parentTraceId is dropped to undefined', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: '',
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'empty string parentTraceId must be coerced to undefined');
|
||||
});
|
||||
|
||||
test('invalid whitespace-only parentTraceId is dropped to undefined', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: ' ',
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'whitespace-only parentTraceId must be coerced to undefined');
|
||||
});
|
||||
|
||||
test('invalid non-UUID string parentTraceId is dropped to undefined', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: 'junk',
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'"junk" parentTraceId must be coerced to undefined');
|
||||
});
|
||||
|
||||
test('invalid oversized string parentTraceId is dropped to undefined', () => {
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: 'a'.repeat(10000),
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'10000-char string parentTraceId must be coerced to undefined');
|
||||
});
|
||||
|
||||
test('invalid UUID v1 parentTraceId is dropped to undefined', () => {
|
||||
// Version nibble is 1, not 4 — rejected by UUID v4 regex
|
||||
const uuidV1Like = 'aaaaaaaa-bbbb-1ccc-8ddd-eeeeeeeeeeee';
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: uuidV1Like,
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'UUID v1 parentTraceId must be dropped to undefined');
|
||||
});
|
||||
|
||||
test('invalid UUID v4 missing hyphens parentTraceId is dropped to undefined', () => {
|
||||
// 32 hex chars, no hyphens
|
||||
const noHyphens = '1234567812345678123456781234567812';
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: noHyphens,
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'UUID v4 missing hyphens must be coerced to undefined');
|
||||
});
|
||||
|
||||
test('invalid UUID v4 with extra chars parentTraceId is dropped to undefined', () => {
|
||||
const withExtra = randomUUID() + 'x';
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: withExtra,
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'UUID v4 with trailing extra char must be coerced to undefined');
|
||||
});
|
||||
|
||||
test('valid UPPERCASE UUID v4 parentTraceId is propagated (case-insensitive)', () => {
|
||||
const upperUUID = randomUUID().toUpperCase();
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: upperUUID,
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, upperUUID,
|
||||
'uppercase UUID v4 parentTraceId must be propagated as-is');
|
||||
});
|
||||
|
||||
test('valid lowercase UUID v4 parentTraceId is propagated', () => {
|
||||
const lowerUUID = randomUUID(); // crypto.randomUUID() is always lowercase
|
||||
const event = makeDispatchEvent({
|
||||
command: 'plan',
|
||||
result: { kind: 'ok', data: null },
|
||||
parentTraceId: lowerUUID,
|
||||
});
|
||||
assert.strictEqual(event.parentTraceId, lowerUUID,
|
||||
'lowercase UUID v4 parentTraceId must be propagated');
|
||||
});
|
||||
});
|
||||
|
||||
describe('makeDispatchEvent — result variants', () => {
|
||||
test('ok result shape', () => {
|
||||
const event = makeDispatchEvent({
|
||||
|
||||
@@ -179,12 +179,89 @@ describe('Hub + logger — event shape', () => {
|
||||
);
|
||||
});
|
||||
|
||||
test('event.parentTraceId is undefined in P1.3', () => {
|
||||
test('event.parentTraceId is undefined when req omits parentTraceId (backward-compat with P1.3)', () => {
|
||||
const tracking = makeTrackingLogger();
|
||||
const hub = makeHub(tracking);
|
||||
hub.dispatch({ family: 'plan', subcommand: '' });
|
||||
assert.strictEqual(tracking.calls[0].parentTraceId, undefined,
|
||||
'parentTraceId must be undefined in P1.3');
|
||||
'parentTraceId must be undefined when req does not include it');
|
||||
});
|
||||
|
||||
test('dispatch passes req.parentTraceId through to the emitted event', () => {
|
||||
const tracking = makeTrackingLogger();
|
||||
const hub = makeHub(tracking);
|
||||
const parentId = 'ffffffff-0000-4000-8000-aaaaaaaaaaaa';
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: parentId });
|
||||
assert.strictEqual(tracking.calls[0].parentTraceId, parentId,
|
||||
'parentTraceId must be present on the event when passed via req');
|
||||
});
|
||||
|
||||
test('multiple dispatches with the same parentTraceId all carry that parentTraceId on their events', () => {
|
||||
const tracking = makeTrackingLogger();
|
||||
const hub = makeHub(tracking);
|
||||
const sharedParentId = 'cccccccc-0000-4000-8000-111111111111';
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: sharedParentId });
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: sharedParentId });
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: sharedParentId });
|
||||
for (const event of tracking.calls) {
|
||||
assert.strictEqual(event.parentTraceId, sharedParentId,
|
||||
'every child dispatch must carry the shared parentTraceId');
|
||||
}
|
||||
});
|
||||
|
||||
test('each dispatch still gets a unique traceId even when parentTraceId is shared (correlation tree invariant)', () => {
|
||||
const tracking = makeTrackingLogger();
|
||||
const hub = makeHub(tracking);
|
||||
const sharedParentId = 'dddddddd-0000-4000-8000-222222222222';
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: sharedParentId });
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: sharedParentId });
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: sharedParentId });
|
||||
const traceIds = tracking.calls.map(e => e.traceId);
|
||||
const unique = new Set(traceIds);
|
||||
assert.equal(unique.size, 3,
|
||||
'each dispatch must produce a unique traceId even when parentTraceId is shared');
|
||||
});
|
||||
});
|
||||
|
||||
// ─── Invalid parentTraceId silently dropped at the Hub seam ─────────────────
|
||||
|
||||
describe('Hub + logger — invalid parentTraceId handling', () => {
|
||||
test('dispatch with invalid parentTraceId still emits event with parentTraceId: undefined', () => {
|
||||
const tracking = makeTrackingLogger();
|
||||
const hub = makeHub(tracking);
|
||||
|
||||
// Send an invalid parentTraceId — not a UUID v4
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: 'junk' });
|
||||
|
||||
assert.equal(tracking.calls.length, 1, 'onEvent must still be called once');
|
||||
const event = tracking.calls[0];
|
||||
// Factory must coerce invalid parentTraceId to undefined — logger never sees the bad value
|
||||
assert.strictEqual(event.parentTraceId, undefined,
|
||||
'event.parentTraceId must be undefined when an invalid value was passed');
|
||||
});
|
||||
|
||||
test('dispatch with invalid parentTraceId does NOT trigger the logger-failure warn path', () => {
|
||||
// The _notifyLogger warn path fires only when logger.onEvent throws.
|
||||
// Silent coercion in the factory means the invalid parentTraceId never reaches
|
||||
// the logger — so the throwing/warn code path must stay dormant.
|
||||
const stderrOutput = captureStderr(() => {
|
||||
const throwingLogger = {
|
||||
// This logger would throw if it ever saw a non-UUID parentTraceId value, but it
|
||||
// must never be reached — the factory drops it before calling the logger.
|
||||
onEvent(event) {
|
||||
if (event.parentTraceId !== undefined) {
|
||||
throw new Error('factory passed invalid parentTraceId to logger');
|
||||
}
|
||||
},
|
||||
};
|
||||
const hub = makeHub(throwingLogger);
|
||||
hub.dispatch({ family: 'plan', subcommand: '', parentTraceId: '' });
|
||||
});
|
||||
|
||||
// If the logger had thrown, the Hub would have emitted a level:warn to stderr.
|
||||
// Empty stderr confirms the factory silently dropped the bad value before calling onEvent.
|
||||
assert.equal(stderrOutput, '',
|
||||
'no stderr warn must appear — factory coerces invalid parentTraceId without involving logger');
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user