HarperFast / HarperFast/documentation

logging/overview.md and logging/api.md document contradictory hdb.log entry formats

Open
#657 0 comments 0 reactions 0 assignees View on GitHub
content
Dominant language
MDX
Stars
9
Forks
9
Avg merge
2d 12h
Merged PRs (30d)
32

Description

### What's wrong

Two reference pages document the `hdb.log` entry format with **different field orders**, and both present it as "the standard format." One of them is wrong.

| Page | Documented format |
| --- | --- |
| [`reference/logging/overview.md:26`](reference/logging/overview.md#L26) | ` [/] [] ...[]: ` |
| [`reference/logging/api.md:128`](reference/logging/api.md#L128) | ` [] [/]: ` |

`overview.md` puts thread before level; `api.md` puts level before thread. `overview.md` also documents a trailing `[]` field that `api.md` omits entirely, and its worked example at `:32` follows its own ordering:

```
2023-03-09T14:25:05.269Z [main/0] [notify]: HarperDB successfully started.
```

`api.md:134` additionally gives a distinct `TaggedLogger` form, ` [] []: `, with no thread field — which may be correct, may be a third variant, or may just be the same disagreement again.

### Which one is right

**Not determined.** I traced the emitter as far as `utility/logging/harper_logger.ts:778`:

```js
function logToFile(log) {
let entry = `${new Date().toISOString()} ${log}${log.endsWith('\n') ? '' : '\n'}`;
```

That prepends only the ISO timestamp — every bracketed field is assembled by callers upstream, so the ordering is not visible at this layer. Settling it needs either a sample from a running instance or a trace of the call sites that build `log`. **That is step one for whoever picks this up**; please do not resolve it by picking the more plausible-looking page.

Also worth confirming while there: whether `[]` still exists as a field, and whether the `TaggedLogger` form genuinely drops the thread or whether that is the same error a third time.

### Why this is worth fixing beyond the inconsistency

This is not only a reader-facing problem. Both files are declared **whole-file sources** for the `logging` rule in [`@harperfast/skills`](https://github.com/HarperFast/skills):

```yaml
- path: reference/v5/logging/overview.md
role: primary
- path: reference/v5/logging/api.md
role: primary
```

The generator concatenates both and hands them to the model as one undifferentiated block with no per-source labels. Faced with two contradictory formats, it silently emitted only `api.md`'s ordering and dropped `overview.md`'s `tags` field, its worked example, and its field table (`thread/id` values `main`/`http`/`job`; `tags` values `custom-function`/`auth-event`). The generated rule's own "When to Use" advertises helping an agent "understand the log entry format."

Nothing flags this. `validate-generated.mjs` passes — it checks structure (manifest consistency, frontmatter, `sourceCommit`/`inputHash`, AGENTS.md round-trip, source-exists, byte-identical slices), not agreement between sources. So a contradiction in our docs is laundered into agent-facing rules with no signal, and whichever page the model happens to favor becomes the one agents act on.

The skills-side manifest cannot fix this. A generator can pick one of two contradictory inputs, but it cannot know which is true.

### Suggested fix

1. Determine the actual emitted format (live sample or trace the callers of `logToFile`).
2. Correct whichever page is wrong, and reconcile the `[]` field and the `TaggedLogger` variant.
3. Prefer having **one** page own the format and the other link to it, rather than restating it. Two independent statements of the same format is what produced this.
4. Check the v4 versioned copies under `reference_versioned_docs/version-v4/` against a v4 harper ref before touching them — do not assume v4 matches v5.

### How this surfaced

Found during a coverage audit of docs-driven skill rule generation, which was itself prompted by a confirmed content loss in a different rule (HarperFast/skills#81). This one is a distinct failure mode: not material dropped for lack of an anchor, but two sources disagreeing and the disagreement being resolved silently.

sent with Claude Opus 5

Contributor guide

Open the contributing guide

Research direction

Start by tracing callers that build log entries into utility/logging/harper_logger.ts:778, or capture a sample from a running instance. Compare the result with reference/logging/overview.md and reference/logging/api.md, including the tags and TaggedLogger forms, then check the v4 copies before editing. Done means the documented formats agree with the emitter and one page owns the canonical format.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, observability
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.