activity: add activity read queries

[Kzoeps]

Summary

• Add get, list, and search activity query Lexicons and Lua handlers.
• Register the activity module and add offline fixtures and contract tests.
• Serialize nullable indexedAt values in owned views.

Stack

Depends on #11 (api/organization-queries), which depends on #10 (api/profile-queries).

Validation

Generated/static checks passed after the latest foundation propagation. Full pnpm check was unavailable in this worktree because dependencies were not installed; HTTP contract tests still require a separately approved disposable target.

Summary by CodeRabbit

• New Features
  • Added public endpoints to retrieve, filter, and search activity records.
  • Activity results include author and contributor details when available, with support for filters, sorting, and cursor-based pagination.
• Documentation
  • Documented activity endpoint behavior, available filters, pagination, and API requirements.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: c7e644fd-5aba-4169-ad9f-8d17af07a9ab

📥 Commits

Reviewing files that changed from the base of the PR and between d56d9ea and 9ea9090.

📒 Files selected for processing (24)

• hypercerts-api/README.md
• hypercerts-api/lexicons/org.hypercerts.claim.getActivity.json
• hypercerts-api/lexicons/org.hypercerts.claim.listActivities.json
• hypercerts-api/lexicons/org.hypercerts.claim.searchActivities.json
• hypercerts-api/lua/endpoints/getActivity.lua
• hypercerts-api/lua/endpoints/listActivities.lua
• hypercerts-api/lua/endpoints/searchActivities.lua
• hypercerts-api/lua/shared/activity.lua
• hypercerts-api/lua/shared/activityList.lua
• hypercerts-api/lua/src/getActivity.lua
• hypercerts-api/lua/src/listActivities.lua
• hypercerts-api/lua/src/searchActivities.lua
• hypercerts-api/manifest.json
• hypercerts-api/modules/activity/manifest.json
• hypercerts-api/package.json
• hypercerts-api/tests/contracts/activity.contract.test.js
• hypercerts-api/tests/fixtures/activities.js
• hypercerts-api/tests/fixtures/fixtures.test.js
• hypercerts-api/tooling/activity.test.js
• hypercerts-api/tooling/build-lua.test.js
• hypercerts-api/tooling/lexicons.test.js
• hypercerts-api/tooling/lua-bundles.js
• hypercerts-api/tooling/seed.js
• hypercerts-api/tooling/seed.test.js

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The API adds public queries to retrieve, list, and search indexed activities. Responses include hydrated author and contributor data. Listing and search support filters, ordering, and cursor pagination.

Changes

Activity API

Layer / File(s)	Summary
Activity lookup and hydration hypercerts-api/lexicons/org.hypercerts.claim.getActivity.json, hypercerts-api/lua/shared/activity.lua, hypercerts-api/lua/endpoints/getActivity.lua, hypercerts-api/lua/src/getActivity.lua, hypercerts-api/tests/fixtures/*, hypercerts-api/tests/contracts/activity.contract.test.js, hypercerts-api/tooling/activity.test.js	The lookup query validates an activity AT-URI and returns the indexed activity with author and contributor data. Contributor-information records resolve by URI and CID. Missing related records are represented as null.
Activity listing and search hypercerts-api/lexicons/org.hypercerts.claim.listActivities.json, hypercerts-api/lexicons/org.hypercerts.claim.searchActivities.json, hypercerts-api/lua/shared/activityList.lua, hypercerts-api/lua/endpoints/{listActivities,searchActivities}.lua, hypercerts-api/lua/src/{listActivities,searchActivities}.lua, hypercerts-api/tests/contracts/activity.contract.test.js, hypercerts-api/tooling/activity.test.js	The list and search queries combine validated filters, sort by timestamp and URI, and paginate with direction-bound cursors. Search checks title and short description. Returned activity views include hydrated related records.
Registration, fixtures, and validation hypercerts-api/manifest.json, hypercerts-api/modules/activity/manifest.json, hypercerts-api/tooling/{lua-bundles.js,build-lua.test.js,lexicons.test.js,seed.js,seed.test.js}, hypercerts-api/package.json, hypercerts-api/README.md	The manifests and bundle configuration register the activity queries and their lexicons. Default fixture seeding and contract tests include activity data. The README documents the endpoints and notes that activity query HTTP proof remains unrun.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ActivityQuery
  participant PostgreSQL
  Client->>ActivityQuery: Submit filters, search, and cursor
  ActivityQuery->>PostgreSQL: Query and order matching activities
  PostgreSQL-->>ActivityQuery: Return activity rows
  ActivityQuery->>PostgreSQL: Load related author and contributor records
  PostgreSQL-->>ActivityQuery: Return related records
  ActivityQuery-->>Client: Return hydrated activities and optional cursor

Loading

Merge Risk: ⚪ Minimal · up to 9ea90

This change adds public, read-only activity lookup, listing, and search queries with contributor hydration and cursor pagination. No concrete defects were found, and the two raised concerns were shown to be unfounded. The documentation notes that end-to-end HTTP validation is still pending. Running the contract tests against a disposable instance before release would confirm runtime behavior, but nothing identified blocks the merge.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to 9ea90

The new unauthenticated queries expose database search and contributor hydration to public callers. Page limits constrain returned activities but do not establish a complete processing budget. Read-only operations and exact record matching limit other risks; upstream resource limits and deployed behavior remain unverified.

Retained concerns

• Medium · security · inferred: The new public collection-query and hydration paths do not establish an end-to-end work budget. A maximum of 100 returned activities does not cap database search and sorting work or the contributors projected and resolved within each activity. Deduplication and 500-reference batches reduce individual lookup size but do not cap total hydration work. This creates an inferred availability risk for shared API and database resources if upstream validation and runtime budgets are insufficient; exploitability and the exact increase over base exposure remain unresolved.

Security review details

Security Blast Radius

• inferred — Configured public callers can query indexed activities across repository owners and cause related-record reads in the same database. Potential resource contention extends to shared API and database capacity. The inspected path does not grant write privileges or establish cross-environment authority; control over unusually large stored contributor arrays depends on unverified ingestion rules.

Security Findings and Attack Paths

• inferred — A public caller can request broad listing or substring search and trigger hydration of every contributor in the returned records. Repetition could amplify database and worker demand if outer controls are insufficient. This is an inferred availability attack path, not a verified vulnerability; producer bounds and deployed execution budgets remain unknown.

Trust Boundaries and Controls

• observed — Request selectors remain database values: SQL placeholders carry filters, search text, and cursor values, while sort direction is validated before selecting fixed SQL fragments. Public reads are intentional, and URI/CID matching constrains contributor-information identity. These controls counter injection and version-substitution concerns without bounding total processing cost.

Resilience and Maintainability Implications

• observed — Hydration deduplicates related-record identifiers and chunks contributor-information lookups into groups of 500. These reduce redundant work and individual query size, but the number of batches and the actor-profile identifier set still grow with stored contributor fanout.

Hardening Proposals

• proposed — Establish an explicit end-to-end budget for public activity queries: confirm enforced ingestion and contributor-count limits, bound search input and aggregate hydration work where necessary, and validate query execution and admission budgets against broad searches and high-fanout records. These are proposals pending verification of existing upstream controls.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the main changes and validation status, but it does not use the required template sections and omits the required Why and Checklist content.	Update the description to include the headings What this changes, Why, How to test, and Checklist. Explain the motivation, provide explicit test instructions and results, and mark each checklist item. Retain the dependency and validation de…
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 107 functions across 17 files. (7 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the addition of activity read queries, including the get, list, and search functionality.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Description check

Resolution

Update the description to include the headings What this changes, Why, How to test, and Checklist. Explain the motivation, provide explicit test instructions and results, and mark each checklist item. Retain the dependency and validation details where relevant.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 107 functions across 17 files. (7 skipped: 7 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.9% Duplication on New Code

See analysis details on SonarQube Cloud