Skip to content

refactor(catalog): share model matching and enrichment core - #594

Open
wz-gsa wants to merge 2 commits into
mainfrom
feat/shared-model-catalog-core
Open

wz-gsa wants to merge 2 commits into
mainfrom
feat/shared-model-catalog-core

Conversation

@wz-gsa

@wz-gsa wz-gsa commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Extract the existing precision matcher, provider preference, non-chat filtering and metadata enrichment into one pure module shared by repository-time catalog generation and the forthcoming startup adapter. Preserve existing builder exports, output, diagnostics and authoring defaults. Runtime callers can leave unknown limits absent.

Supports #425 and GSA-TTS/agentic-coding-quickstart#695. This foundation does not activate live discovery or complete their release gates. Pending #593 touches the exclusion policy; reconcile its reviewed change in the shared module rather than retaining a second policy.

Review follow-up

At 5d23b205d579932427fc3d17ef2e798d64d5c170, added ADR 0006 documenting validated-input preconditions, metadata/default and failure contracts, capability provenance, and extraction rationale. Narrowed the empty-feed test to its actual builder assertion and removed the vacuous array mapping. Independent static QA found no actionable defect; primary verified the clean review checkout, all committed bytes/modes, ancestry and two-file repair delta.

Module-size exception

Under Coding Practices §13.3, the 466-line model-catalog-core.mjs keeps identity normalization, precision/ranking, backend preference, non-chat filtering and metadata enrichment as one cohesive policy. Co-location makes ordering and assumptions reviewable and gives authoring and future runtime consumers one implementation. A mechanical split adds module edges without a distinct responsibility; I/O, credentials, rendering and lifecycle remain outside. Revisit the boundary if new concerns are added.

Current-head verification

Isolated nonroot, network-disabled Linux container; Node 26.13.0:

node --test 'integrations/providers/usai/tests/**/*.test.mjs'
245 passed; 0 failed; 1 existing optional-candidate skip
make validate: passed (existing advisory warnings retained)
node .github/linters/run-markdownlint.mjs: passed
managed commit hooks: passed, including Gitleaks and repository hooks
managed push hook: passed; range secret scan found no leaks

No runtime implementation changed in this repair. The full kit-suite result below is historical at the original head; current-head hosted CI remains required. The reviewer's change request awaits re-review.

Original-head validation

At 4db49c6, isolated nonroot/no-network Linux container:

provider catalog tests: 245 passed, 1 existing optional-candidate skip
make test-kits: all suites passed
make validate: passed (existing advisory warnings retained)
managed commit and push hooks: passed
independent fixed-head QA/security: no actionable findings

All-files pre-commit exposed pre-existing whitespace, formatting and lint findings in unrelated teaching fixtures and OCI verifier files; those changes were restored. No all-files-green claim. The initial minimal Node22 run lacked jq and exposed a copied-fixture dependency omission; the fixture now copies the new module. Final full suite ran with Node26. Current hosted CI remains required.

Rollback and security

Revert this extraction before dependent runtime delivery. No network, credential access, dependency pins or configuration authority added. Existing behavior assertions are retained; the vacuous new array-mapping assertion was removed. Snapshots are unchanged. The core assumes validated ingestion and is not itself a sandbox.

Eligibility & Accountability

The submitting human @wz-gsa explicitly confirmed these attestations in the coordinating session:

  • I am a federal employee or contractor.
  • I understand these changes and accept accountability for them.
  • I have the right to release this work under the repository’s CC0 dedication.

Independent applicable CODEOWNER review and exact-head merge authorization remain required.

AI assistance

OpenCode assisted implementation, the ADR/review repair, isolated validation and independent review. Human review and exact-head merge authorization remain required.

Co-authored-by: OpenCode

Supports #425 without changing repository-time catalog output.

Co-authored-by: OpenCode <153217227+wz-gsa@users.noreply.github.com>

@mogul mogul left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST CHANGES — engineering-policy requirements

AI-assisted adversarial review by OpenCode (GPT 6.1), including an independent review sub-agent, requested by @mogul, of #594 at 4db49c62e7281dfde08b7cc757a54aa7a20b107a.

Blockers — not demonstrated functional/security defects

  1. P2 — Record the new shared-core boundary in an ADR. integrations/providers/usai/scripts/build-catalog.mjs:71–81 imports the new module; scripts/model-catalog-core.mjs:420–465 introduces the shared enrichment interface. This changes a module boundary and exposes caller-owned validation, diagnostic and failure contracts. Playbook Coding Practices §11.1 requires a decision record for that change. Existing repo-time refresh ADR 0003 and isolation discovery ADR 0004 do not record this extraction's interface. Add or amend a focused ADR covering validated-input preconditions, absent runtime limits versus authoring defaults, preserved throwing behavior, capability provenance responsibility, and the rationale for extracting ahead of the next consumer. No future adapter implementation is requested.

  2. P2 — Supply the required size-exception justification. The new integrations/providers/usai/scripts/model-catalog-core.mjs is 466 lines. Coding Practices §13.3 permits cohesive 400–600-line modules with written justification in the PR description; none is present. Explain why identity/filtering/enrichment belong together and acknowledge the exception, or reduce the module below the limit. A mechanical split is not required.

Technical assessment: no demonstrated regression

The extraction preserves tokenizer/precision/ranking and backend preference; the first precise backend match still wins rather than selecting a richer fallback. Provider limits retain independent precedence, missing limits remain absent in the core, and generic authoring defaults remain in the builder. Invalid costs still throw; capability diagnostics return as data and the builder preserves their wording/counts. Existing builder exports remain available, and copied CLI fixtures include the new dependency. The core has no I/O or credential access; purity is not process containment and does not authorize runtime activation.

Advisories

  • tests/model-catalog-core.test.mjs:109–112 maps over an empty array without calling the core. Narrow its “runtime empty membership” claim; it is not proof of an implemented runtime consumer.
  • The builder/core comparison at test lines 177–186 shares the implementation under test; retain the independent byte-exact refresh and precision/capability regressions as the semantic oracle.
  • Reconcile #593's reviewed cohere-v4 exclusion in the shared core when integrating the two PRs. Its absence here preserves base behavior, not an extraction regression, and the PR already identifies this overlap.

Verification and limits

All eight reported check runs succeed (seven check types, with two title runs). Hosted logs and merge-parent inspection confirm CI merge 30c228ef571ca14564f2495cf979ae59ee264e1c contains this exact head and base 1ff65efd684655304864aae502ab7e88fae16973.

Observed: provider suite 245 passed, 0 failed, 1 optional CATALOG_DRIFT_WORKFLOW skip; OpenCode 69 passed, normalizer 18 passed, other kit suite 87 passed, OCI 1 passed. Python 3.12/3.13 each report 829 passed plus 58 subtests. Validators, provider contracts, generated indexes, Ruff/formatting and Markdown lint pass. Unsafe-shell scan: 0 errors/warnings; inspected npm/Python audits: no known vulnerabilities. Existing advisory validator warnings remain. Added diff lines have no trailing whitespace; marker inspection found no credential values or added executable/network paths.

Human eligibility/accountability and AI disclosure are present. No PR code executed locally, dependencies installed, or workspace files modified. No live USAi/sandbox qualification, full local pre-commit rerun, branch-protection enforcement or reviewer-team membership verification. This AI-assisted review is posted under the requesting account, not independent human review or merge/production authorization.

Address architecture and test-claim feedback on #594. Retain authoring empty-feed rejection without claiming runtime coverage.

Co-authored-by: OpenCode <153217227+wz-gsa@users.noreply.github.com>
@wz-gsa
wz-gsa requested a review from mogul November 13, 2026 21:49

@basiliskus basiliskus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: approve — 5d23b205d579932427fc3d17ef2e798d64d5c170

Must fix before merge: none.

Prior findings from the original-head review of GSA-TTS/agentic-coding-patterns#594:

  1. Resolved — shared-core ADR/interface contract. docs/decisions/0006-shared-model-catalog-core.md:55–107 now documents validated-input preconditions, caller-owned bounds and failure policy, absent core limits versus authoring defaults, throwing behavior, and capability provenance. The considered options explain extracting separately from runtime delivery. Resolved in 5d23b205.
  2. Resolved — module-size exception. integrations/providers/usai/scripts/model-catalog-core.mjs:1–466 is covered by the PR description's written cohesive-module justification under Coding Practices §13.3, also recorded at docs/decisions/0006-shared-model-catalog-core.md:118–128. Resolved in 5d23b205 and the updated PR description.

No new actionable findings. The empty-feed test now asserts only the implemented builder behavior. This approval covers the pure extraction, not runtime activation or live qualification. The still-open catalog refresh must retain its exclusion-policy change when integrated with this extraction.

Checks and gaps: Local Node 22 provider suite: 245 passed, 0 failed, 1 optional skip; changed JavaScript syntax checks pass. Hosted CI exercised merge 78d8031b8c13b741b236d56aeddb420997857c2d, whose parents are this head and newer base 395319f2a22a004a6fedb12196b33fab6a2b5995. Local validation remains blocked by missing Python dependencies, including after an offline, no-sync uv attempt; hosted validators passed. No live gateway/VM qualification or full local pre-commit/security rerun. Human CODEOWNER review and merge authorization remain required.

Assisted-by: OpenCode [GPT 6.1 Sol Latest Guardrails Defaultv2] skill:change-review

@basiliskus
basiliskus enabled auto-merge November 13, 2026 22:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants