feat(server): add agent catalog endpoint backed by registry metadata

[moises-cisneros]

Closes #87

Stacked on #86 (which is stacked on #84); retarget to main as each one merges.

Summary

Adds a read-only Serverpod agent endpoint (list and get) that serves an AgentSummary catalog built from the Identity Registry metadata through the Soroban ledger adapter from #86.

• SorobanLedger gains totalAgents and agentMetadata, and the XDR encoder gains a string argument.
• AgentCatalogService (pure Dart) enumerates ids 0..total-1 with 4 workers, skips agents with missing or invalid metadata (this drops the superseded demo agents 0-6), keeps the highest registryId when a metadata id repeats, and caches the list for 60 s.
• On an outage the service returns the stale cache if there is one; otherwise it throws the typed AgentCatalogUnavailable. An outage never produces an empty or partial list.
• The endpoint builds its default service lazily (PULS3_STELLAR_* env vars, an 8 s RPC timeout) and has a test override, because the generated Endpoints() only calls no-argument constructors.
• Generated server and client code is committed (serverpod_cli 3.4.13).

Acceptance criteria

• agent endpoint with list and get returning AgentSummary (no rating).
• Invalid-metadata agents skipped; outage never returns an empty list.
• 60 s cache with stale fallback and typed AgentCatalogUnavailable.
• Generated client committed; serverpod generate leaves no diff.

Verification evidence

cd puls3_server
dart test test/unit              -> 152 passed
dart analyze --fatal-infos       -> No issues found
serverpod generate (3.4.13)      -> git diff --exit-code -- puls3_server puls3_client: clean

• New ledger fixtures were recorded read-only from soroban-testnet (total_agents = 15, agent 7 name = "Ledger Scout", agent 7 id = "agt-001"). Nothing was signed or broadcast.
• The first verification found two untested scenarios (lazy default wiring and the no-rating model). They now have tests and the specs were aligned with the design.

Notes for reviewers

• Size is above the 400-line budget mostly because of generated code and fixtures (about 300 hand-written lines). Requesting size:exception.
• Local Dart is 3.10 and CI uses 3.11, so generated output came from an older SDK. It was byte-stable across runs; the CI generated-diff gate is the final check.
• A cold load makes roughly 7 simulate calls per valid agent plus 1 per orphan, bounded to 4 workers. A stale list is served with no age limit because nothing in the design sets one.
• There is no rating on chain (reputation_registry is not deployed), so AgentSummary has none; the Flutter change decides the display default.
• Adds a direct meta: ^1.17.0 dependency (already in the lock) for @visibleForTesting.

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	90183fa
Status:	⚡️  Build in progress...

View logs

[TOMOKI977]

La implementación del catálogo está bien resuelta: caché de 60 s, fallback a datos stale, agentes inválidos omitidos y excepción tipada cuando no hay datos. Los criterios del issue se cumplen.

El punto pendiente es de diseño, no de código: el endpoint no coincide con el contrato de API propuesto en #77 (docs/architecture/api.md).

• Contrato: CatalogEndpoint.listAgents / getAgent(int), que devuelve un AgentSummary con agent, rating, paidHireCount y active.
• Este PR: AgentEndpoint.list / get(String), con un modelo plano (registryId, skills: List<String>, priceUsdcStroops).

Antes de mergear necesitamos decidir cuál de los dos manda y alinear el otro, para no tener cliente, servidor y documentación diciendo cosas distintas. Lo coordinamos en #77.

[TOMOKI977]

Approving. We decided to keep your AgentEndpoint design and align the contract to it instead: #99 updates docs/architecture/api.md to AgentEndpoint.list() / get(id) and copies AgentSummary and AgentCatalogUnavailable exactly, so no changes are needed here.

One thing the contract now states explicitly, worth keeping in mind for #96 and #92: createHire takes the on-chain registryId as agentId, while get takes the metadata id (agt-001).

Merge note: retarget this to main once #86 merges, so CI runs before merging.