refactor(knowledge): hide asset reads behind owner query

[kl3inIT]

Summary

• add Asset-owned KnowledgeAssetRetrievalQuery with a package-private transactional JPA implementation
• migrate Retrieval existence, authorization-scope, and catalog reads away from Asset repositories
• pin exact consumers and repository isolation with Modulith tests

Architecture review

• implements condition 1 of the recorded Retrieval closure ACCEPT WITH CHANGES verdict
• configured Fable 5 remained unavailable because the account reached its monthly spend limit; the existing clean Codex ultra fallback verdict explicitly prescribed this seam
• Retrieval remains open for Organization, Source Ledger citation, Graph verifier, and adapter seams

Verification

• failing-first repository isolation characterization captured the three old consumers
• focused Asset query/catalog/scope/Modulith tests: passed
• PostgreSQL external-principal + API admin-resource integration tests: passed
• full :core:test :apps:api:test :apps:worker:test: passed
• terminating repository-wide clean test: passed (99 tasks)
• docs operating-model check: passed (478 Markdown files, 8 mirrored pairs)
• release policy: passed (40 tests, Node 24.15)
• PR diff: 18 changed paths

Release disposition

skip-release: internal package-boundary refactor with no user-facing behavior change

Summary by CodeRabbit

• New Features

  • Added a unified retrieval capability for checking asset availability, authorization scopes, and current catalog information.
  • Improved catalog and evidence lookups through consistent organization-scoped retrieval.

• Documentation

  • Clarified ownership and access boundaries for asset and retrieval data.

• Tests

  • Added coverage for retrieval behavior, empty-input handling, catalog lookups, authorization, and module dependency boundaries.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Asset module adds KnowledgeAssetRetrievalQuery and a JPA implementation. Retrieval consumers now use this query instead of Asset repositories. Tests and architecture documentation enforce the new module boundary.

Changes

Asset retrieval boundary

Layer / File(s)	Summary
Define and implement the retrieval query core/src/main/java/com/orgmemory/core/knowledge/asset/..., core/src/test/java/com/orgmemory/core/knowledge/asset/...	Adds the KnowledgeAssetRetrievalQuery contract and transactional implementation. The implementation validates inputs, short-circuits empty collections, delegates to repositories, and returns immutable results.
Migrate Retrieval consumers and verify the boundary core/src/main/java/com/orgmemory/core/knowledge/retrieval/..., core/src/test/java/com/orgmemory/core/knowledge/retrieval/..., core/src/test/java/com/orgmemory/core/ModulithVerificationTests.java, ARCHITECTURE.md	Updates authorization, catalog, and evidence-scope components to use the query. Tests and architecture documentation record that Retrieval has no direct Asset repository dependency.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• kl3inIT/OrgMemory#221: Establishes a related Asset-owned query boundary for Graph.
• kl3inIT/OrgMemory#187: Establishes the knowledge.asset module boundary used by this query.
• kl3inIT/OrgMemory#60: Changes related Retrieval catalog and version lookup paths.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: moving knowledge asset reads behind an Asset-owned query.
Description check	✅ Passed	The description explains the refactor, verification evidence, architecture scope, and release disposition, but omits the template's Documentation impact section.
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.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/modulith-retrieval-asset-query

---

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.}

[github-actions]

Tegami

This repository uses Tegami to manage releases. When your changes affect published packages, add a changelog file under .tegami/ before merging.

Create a changelog → · Changelog format

Release preview

Package	Bump	Version
orgmemory	minor	0.1.1 → 0.2.0

This PR does not add changelog files. Pending changelogs from other branches are included in the preview above.

Run pnpm run tegami locally to create a changelog interactively.

_{Managed by Tegami.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ARCHITECTURE.md`:
- Around line 150-155: Update the architecture documentation around the
Asset-Retrieval boundary to add a decision record for
KnowledgeAssetRetrievalQuery. Compare direct Asset repository access with
Asset-owned query-boundary alternatives, and require this
persistence/domain-boundary decision to be resolved before merge alongside the
existing architecture evidence.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 18bd2b98-98cf-42d6-8fd1-0cd2df322041

📥 Commits

Reviewing files that changed from the base of the PR and between ce1a970 and 9a760b8.

⛔ Files ignored due to path filters (5)

• docs/increments/active/2026-07-31-spring-modulith-package-refactor/plan.md is excluded by !docs/**
• docs/specs/domains/asset-registry.md is excluded by !docs/**
• docs/specs/domains/secure-retrieval.md is excluded by !docs/**
• docs/tests/domains/asset-registry.md is excluded by !docs/**
• docs/tests/domains/secure-retrieval.md is excluded by !docs/**

📒 Files selected for processing (13)

• ARCHITECTURE.md
• core/src/main/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQuery.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeAssetRetrievalQuery.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/package-info.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/AuthorizationResourceDirectory.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogService.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolver.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/package-info.java
• core/src/test/java/com/orgmemory/core/ModulithVerificationTests.java
• core/src/test/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQueryTests.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/ExternalPrincipalRetrievalIntegrationTests.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogServiceTests.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolverTests.java

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Backend · Java 25

🧰 Additional context used

📓 Path-based instructions (3)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Treat the repository and runtime evidence as the engineering system of record; do not treat chat or Northstar as authoritative.
Before changing a domain, read its specification, test-coverage document, and applicable decision filenames.
Material decisions about domain boundaries, authorization, persistence, publication, concurrency, cache isolation, parity scope, or deployment require an independent architecture challenge and documented alternatives before implementation.
Do not use completed increment documents as the source for current behavior; use them only for history or archaeology.
Before using unfamiliar Spring Boot, Spring Modulith, Spring AI, Gradle, React, Vite, Tailwind, TypeScript, Next.js, or Fumadocs APIs, consult current official documentation, Context7, and the relevant verification skill.
Read docs/guidelines/agent-safety.md before retrieval, AI, MCP, permission, upload, graph, or export work; never commit secrets or customer data.
Keep ddl-auto=validate and pair every persisted-model change with a Flyway migration.
Use the testing harness; a terminating clean test is the JVM context gate, and bootRun is not verification.

Files:

• core/src/main/java/com/orgmemory/core/knowledge/retrieval/package-info.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/package-info.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/ExternalPrincipalRetrievalIntegrationTests.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeAssetRetrievalQuery.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolver.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQuery.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolverTests.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/AuthorizationResourceDirectory.java
• ARCHITECTURE.md
• core/src/test/java/com/orgmemory/core/ModulithVerificationTests.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogService.java
• core/src/test/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQueryTests.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogServiceTests.java

**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

Apply IDE inspection only to edited backend Java files.

Files:

• core/src/main/java/com/orgmemory/core/knowledge/retrieval/package-info.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/package-info.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/ExternalPrincipalRetrievalIntegrationTests.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeAssetRetrievalQuery.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolver.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQuery.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolverTests.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/AuthorizationResourceDirectory.java
• core/src/test/java/com/orgmemory/core/ModulithVerificationTests.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogService.java
• core/src/test/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQueryTests.java
• core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogServiceTests.java

core/src/main/java/com/orgmemory/core/{authorization,knowledge,permission}/**/*.java

⚙️ CodeRabbit configuration file

core/src/main/java/com/orgmemory/core/{authorization,knowledge,permission}/**/*.java: Treat PostgreSQL ACL evidence as canonical and OpenFGA as the relationship
authorization decision point. Authorization must fail closed. Filtering
must happen before ranking, LIMIT, graph traversal, answer generation,
export, and citation rendering. Flag metadata or timing leak paths.

Files:

• core/src/main/java/com/orgmemory/core/knowledge/retrieval/package-info.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/package-info.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeAssetRetrievalQuery.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolver.java
• core/src/main/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQuery.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/AuthorizationResourceDirectory.java
• core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogService.java

🔇 Additional comments (12)

core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeAssetRetrievalQuery.java (1)

1-35: LGTM!

core/src/main/java/com/orgmemory/core/knowledge/retrieval/AuthorizationResourceDirectory.java (1)

5-5: LGTM!

Also applies to: 26-32, 56-56

core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogService.java (1)

3-3: LGTM!

Also applies to: 23-29, 40-40, 60-60, 75-75

core/src/main/java/com/orgmemory/core/knowledge/retrieval/package-info.java (1)

10-12: LGTM!

core/src/test/java/com/orgmemory/core/ModulithVerificationTests.java (1)

795-796: LGTM!

Also applies to: 806-842

core/src/test/java/com/orgmemory/core/knowledge/retrieval/ExternalPrincipalRetrievalIntegrationTests.java (1)

4-4: LGTM!

Also applies to: 343-343

core/src/main/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQuery.java (1)

11-96: LGTM!

core/src/main/java/com/orgmemory/core/knowledge/asset/package-info.java (1)

7-14: LGTM!

core/src/test/java/com/orgmemory/core/knowledge/asset/JpaKnowledgeAssetRetrievalQueryTests.java (1)

30-111: LGTM!

core/src/main/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolver.java (1)

4-4: LGTM!

Also applies to: 42-42, 51-51

core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeCatalogServiceTests.java (1)

11-11: LGTM!

Also applies to: 36-45, 59-59, 68-75, 89-89, 101-101, 118-118

core/src/test/java/com/orgmemory/core/knowledge/retrieval/KnowledgeEvidenceScopeResolverTests.java (1)

4-4: LGTM!

Also applies to: 46-46