feat: materialize canonical foaf:name per agent into trust + spaces graphs (#62)

[tkuhn]

Status

Draft — depends on nanopub-registry#113, which adds the per-account `name` + `nameCreatedAt` fields to the trust-state snapshot JSON. The schema parser is forward-compatible so this PR is safe to merge before the registry change ships (consumers running against an older registry simply produce no `foaf:name` triples), but the live effect only kicks in once both are deployed.

Pairs with nanopub-query#89 (observer-tier permissive grants) — that PR's worked-example query in `design-space-repositories.md` will need a small follow-up doc update to drop the `SERVICE <…/full>` clause, which is intentionally not in this PR (the doc edit only makes sense after #89 lands).

Summary

Consumes the per-account `name` + `nameCreatedAt` fields from the trust-state snapshot and folds them, at materialisation time, into one canonical `foaf:name` triple per approved agent — emitted in the trust-state named graph and mirrored into each new spaces state graph at full-build time.

Result: any consumer reading the trust or spaces state graph gets `?agent foaf:name ?n` directly, with no cross-repo `SERVICE` to `/repo/full`.

Resolution policy

The two layers were decided up front (see PR #89's discussion) to keep the on-disk schema minimal:

• Per-`(agent, pubkey)` (registry, #113): keep the name from the intro with the latest `dct:created`. First write wins when no current timestamp exists; subsequent writes replace iff strictly newer. Multi-`foaf:name` on a single intro: `MIN(?name)` lex tiebreak for determinism.
• Per-agent across keys (this PR, `TrustStateLoader.resolveCanonicalNames`): pick the row with `MAX(ratio)` from the agent's approved (`loaded` / `toLoad`) account rows; ties → `MIN(name)` lex. Agents with no qualifying row are simply absent from the result map (no triple emitted).

Composed: "the most-trusted key's freshest declaration".

Changes

Parser — `TrustStateSnapshot`

• `AccountEntry` extends from 7 to 9 fields, adding optional `name` (`String`) and `nameCreatedAt` (`Instant`).
• New `unwrapDateNullable` handles MongoDB extended JSON (`{"$date": "…"}` or `{"$date": {"$numberLong": "…"}}`), plain ISO-8601 strings, plain numeric epoch-ms, and JSON `null`/missing — so the parser works against any reasonable registry serialiser and against pre-#113 registries (where the fields are absent).

Resolver — `TrustStateLoader`

• New static `resolveCanonicalNames(snapshot)` returning `Map<agent, name>`. Filters to `APPROVED_STATUSES` (`loaded` / `toLoad`), skips rows with null `ratio` or null `name`, picks `MAX(ratio)` per agent, breaks ties on lex-min name.
• `materialize` now emits one ` foaf:name "…"` triple in the trust-state named graph per resolved agent, after the existing `AccountState` rows.

Mirror — `AuthorityResolver.mirrorTrustState`

• After copying approved `AccountState` rows from the trust state graph into the new spaces state graph, additionally walks all `?subj foaf:name ?obj` triples in the trust-state graph and copies them too. The trust loader only emits names for approved agents, so no extra filter is needed here.

Tests

• `TrustStateLoaderTest` (+5): `resolveCanonicalNames_picksRowWithMaxRatio`, `_breaksTiesOnLexMinName`, `_skipsUnapprovedRows`, `_omitsAgentsWithNoName`, `_acceptsToLoadStatusToo`. Pure-logic tests over the resolver function; no RDF4J / Mongo needed.
• `TrustStateSnapshotTest` (+3): `parse_extractsNameAndNameCreatedAtWhenPresent` (extended-JSON `$date`), `parse_acceptsAccountWithoutNameFields` (forward-compat with pre-#113 registry), `parse_acceptsPlainStringNameCreatedAt` (alternative serialisation).
• Existing tests using the 7-arg `AccountEntry` constructor updated to 9-arg with `null, null` for the new fields.

Test plan

• `mvn test` — 177/177 pass locally (was 169; +8 new tests, 5 existing constructor sites updated)
• CI green
• Live verify after #113 + this both deploy:
  • `/trust-state/.json` includes `name` + `nameCreatedAt` per approved account row.
  • Trust state graph contains `?agent foaf:name ?n` triples for approved agents (one per agent, not per pubkey).
  • Spaces state graph (after a full build / pointer flip) mirrors those `foaf:name` triples.
  • Consumer query for session30 returns names without a `SERVICE` clause (drop `SERVICE http://query:9393/repo/full` from feat: validate downward observer-tier grants from admin/maintainer/member (#62) #89's worked-example query and verify same row count).

Compatibility

• Parser is fully forward-compatible: pre-#113 registry → `name`/`nameCreatedAt` parsed as null → no `foaf:name` triples emitted. Same behaviour as today.
• Mirror is harmless when the trust graph has no `foaf:name` triples to copy.
• No data-format change for existing rows; the new triples are purely additive.

🤖 Generated with Claude Code