Derive scope types and WHERE helpers from single source of truth by amikofalvy · Pull Request #2159 · inkeep/agents

amikofalvy · 2026-02-19T07:22:30Z

Summary

Introduce scope-definitions.ts with SCOPE_KEYS as the canonical definition of which columns belong to each scope level (tenant, project, agent, subAgent)
TypeScript scope config types (ProjectScopeConfig, AgentScopeConfig, SubAgentScopeConfig) are now computed from SCOPE_KEYS via mapped types instead of manually defined
scope-helpers.ts uses a generic scopedWhere(level, table, scopes) that iterates over SCOPE_KEYS, eliminating per-level column enumeration. Named wrappers (projectScopedWhere, etc.) are preserved for ergonomics
types/utility.ts re-exports the derived types to preserve all existing import paths (zero changes needed in consumers)

Before (3 independent definitions that can drift)

manage-schema.ts:   const projectScoped = { tenantId: ..., projectId: ... }
types/utility.ts:   type ProjectScopeConfig = { tenantId: string; projectId: string }
scope-helpers.ts:   and(eq(table.tenantId, ...), eq(table.projectId, ...))

After (1 definition, everything else derived)

scope-definitions.ts:   SCOPE_KEYS.project = ['tenantId', 'projectId'] as const
  → types derived:      type ProjectScopeConfig = { [K in ...]: string }
  → WHERE derived:      scopedWhere('project', table, scopes) iterates SCOPE_KEYS.project

Applies on top of PR #2151 (scope-aware query helpers + isolation tests).

Test plan

All 13 scoping isolation tests pass
Full monorepo typecheck passes (14/14 tasks)
Lint passes
Format passes

🤖 Generated with Claude Code

changeset-bot · 2026-02-19T07:22:34Z

🦋 Changeset detected

Latest commit: a85b58a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@inkeep/agents-core	Patch
@inkeep/agents-api	Patch
@inkeep/agents-manage-ui	Patch
@inkeep/agents-cli	Patch
@inkeep/agents-sdk	Patch
@inkeep/agents-work-apps	Patch
@inkeep/ai-sdk-provider	Patch
@inkeep/create-agents	Patch
@inkeep/agents-mcp	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-02-19T07:22:34Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agents-api	Ready	Preview, Comment	Feb 19, 2026 8:20pm
agents-docs	Ready	Preview, Comment	Feb 19, 2026 8:20pm
agents-manage-ui	Ready	Preview, Comment	Feb 19, 2026 8:20pm

amikofalvy · 2026-02-19T10:11:09Z

✅ Rebased on latest main

claude

PR Review Summary

(0) Total Issues | Risk: Low

This PR introduces a well-designed single-source-of-truth pattern for hierarchical scope definitions. The implementation is clean, maintains backwards compatibility, and eliminates the prior three-way drift risk between schema columns, type definitions, and query helpers.

🔴❗ Critical (0) ❗🔴

None.

🟠⚠️ Major (0) 🟠⚠️

None.

🟡 Minor (0) 🟡

None.

💭 Consider (1) 💭

Inline Comments:

💭 Consider: utility.ts:50 Export TenantScopeConfig for completeness alongside other scope config re-exports

✅ APPROVE

Summary: This is an excellent refactor that consolidates three independent definitions (schema columns, TypeScript types, WHERE helpers) into a single source of truth. The type derivation is correct, the generic scopedWhere function is well-implemented, and all existing consumers continue to work unchanged. The named wrappers preserve grep-ability and ergonomics. The only minor observation is that TenantScopeConfig could be re-exported for consistency, but this is a nitpick since it wasn't exported before. Nice work! 🎉

Discarded (5)

Location	Issue	Reason Discarded
`scope-definitions.ts:25-27`	`ScopedTable` uses `any` for column values	Pragmatic tradeoff acknowledged by reviewer — accepts any Drizzle column type; constraints on function parameters provide sufficient safety
`scope-helpers.ts:21-22`	Type assertions `as Record<string, any>`	Standard TypeScript pattern for dynamic key iteration; assertions are safe because constraints guarantee keys exist
`utility.ts:44-50`	Re-exported types lose explicit intersection semantics	Structural equivalence maintained; hierarchy now encoded in SCOPE_KEYS which is actually an improvement
`runtime-schema.ts:41-59`	Parallel scope definitions in runtime schema	Pre-existing pattern; extending unification to runtime schema is outside PR scope and may have valid reasons for separation
`data-access/index.ts`	scope-helpers.ts not exported from barrel	Pre-existing architectural boundary; not introduced by this PR

Reviewers (3)

Reviewer	Returned	Inline Comments	Discarded
`pr-review-architecture`	4	1	3
`pr-review-types`	3	0	3
`pr-review-standards`	0	0	0
Total	7	1	6

Note: One inline comment from architecture reviewer was merged with types analysis (TenantScopeConfig re-export).

claude · 2026-02-19T10:17:21Z

+  AgentScopeConfig,
+  ProjectScopeConfig,
+  SubAgentScopeConfig,
+} from '../db/manage/scope-definitions';


💭 Consider: Export TenantScopeConfig for completeness

Issue: The new scope-definitions.ts exports TenantScopeConfig, but it's not re-exported here with the other scope config types.

Why: Minor asymmetry — TenantScopeConfig was only defined locally in scope-helpers.ts before, so this isn't a regression. However, consumers who need it must import from the deeper path while other scope configs come from this barrel.

Fix:

Suggested change

} from '../db/manage/scope-definitions';

export type {

AgentScopeConfig,

ProjectScopeConfig,

SubAgentScopeConfig,

TenantScopeConfig,

} from '../db/manage/scope-definitions';

Refs:

scope-definitions.ts:35 — TenantScopeConfig export

Introduce scope-definitions.ts with SCOPE_KEYS as the canonical definition of which columns belong to each scope level. All downstream consumers now derive from this single source: - TypeScript scope config types (ProjectScopeConfig, AgentScopeConfig, etc.) are now computed from SCOPE_KEYS instead of manually defined - scope-helpers.ts uses a generic scopedWhere() that iterates over SCOPE_KEYS, eliminating per-level column enumeration - types/utility.ts re-exports the derived types to preserve existing import paths Adding or removing a scope column now requires changing only SCOPE_KEYS. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

claude

PR Review Summary

(0) Total Issues | Risk: Low

This is a re-review after rebase. The PR introduces a well-designed single-source-of-truth pattern for hierarchical scope definitions. The implementation consolidates three previously independent definitions (schema columns, TypeScript types, WHERE helpers) into SCOPE_KEYS, with everything else derived from it. No new issues were identified.

🔴❗ Critical (0) ❗🔴

None.

🟠⚠️ Major (0) 🟠⚠️

None.

🟡 Minor (0) 🟡

None.

💭 Consider (0) 💭

None.

🕐 Pending Recommendations (1)

💭 utility.ts:50 Re-export TenantScopeConfig for API completeness alongside other scope config types

✅ APPROVE

Summary: This is an excellent refactor that consolidates three independent definitions into a single source of truth. The type derivation is correct (SCOPE_KEYS → ScopeConfig<L> → named aliases), the generic scopedWhere() function is well-implemented with safe type assertions, and all existing consumers continue to work unchanged through re-exports. The prior Consider suggestion (re-exporting TenantScopeConfig) remains open but is a minor API completeness nitpick, not a blocking concern. Ship it! 🚀

Discarded (1)

Location	Issue	Reason Discarded
`runtime-schema.ts:41-59`	Parallel scope definitions in runtime schema not consolidated	Pre-existing pattern outside PR scope; extending unification to runtime schema would significantly expand the PR. The manage schema consolidation is the intentional focus.

Reviewers (3)

Reviewer	Returned	Discarded
`pr-review-types`	0	0
`pr-review-standards`	0	0
`pr-review-architecture`	1	1
Total	1	1

Note: Architecture reviewer flagged runtime-schema parallel definitions as a potential future improvement; discarded as pre-existing and outside PR scope.

vercel Bot deployed to Preview – agents-api February 19, 2026 07:24 View deployment

vercel Bot deployed to Preview – agents-docs February 19, 2026 07:25 View deployment

vercel Bot deployed to Preview – agents-manage-ui February 19, 2026 07:26 View deployment

Base automatically changed from feat/scope-query-helpers to main February 19, 2026 10:08

amikofalvy force-pushed the feat/scope-definitions branch from ecc1603 to de35aad Compare February 19, 2026 10:11

vercel Bot deployed to Preview – agents-docs February 19, 2026 10:13 View deployment

vercel Bot deployed to Preview – agents-api February 19, 2026 10:13 View deployment

vercel Bot deployed to Preview – agents-manage-ui February 19, 2026 10:15 View deployment

claude Bot reviewed Feb 19, 2026

View reviewed changes

github-actions Bot deleted a comment from claude Bot Feb 19, 2026

amikofalvy force-pushed the feat/scope-definitions branch from de35aad to a85b58a Compare February 19, 2026 20:13

vercel Bot deployed to Preview – agents-api February 19, 2026 20:18 View deployment

vercel Bot deployed to Preview – agents-docs February 19, 2026 20:19 View deployment

vercel Bot deployed to Preview – agents-manage-ui February 19, 2026 20:20 View deployment

claude Bot reviewed Feb 19, 2026

View reviewed changes

github-actions Bot deleted a comment from claude Bot Feb 19, 2026

amikofalvy merged commit 65f71b5 into main Feb 23, 2026
11 checks passed

amikofalvy deleted the feat/scope-definitions branch February 23, 2026 20:11

claude Bot mentioned this pull request Feb 23, 2026

Fix duplicate resource errors from throwing 500 instead of user frien… #2262

Merged

amikofalvy mentioned this pull request Mar 15, 2026

feat: complete DAL scope helper migration and error handling infrastructure #2701

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Derive scope types and WHERE helpers from single source of truth#2159

Derive scope types and WHERE helpers from single source of truth#2159
amikofalvy merged 1 commit into
mainfrom
feat/scope-definitions

amikofalvy commented Feb 19, 2026

Uh oh!

changeset-bot Bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

amikofalvy commented Feb 19, 2026

Uh oh!

claude Bot left a comment

Uh oh!

claude Bot Feb 19, 2026

Uh oh!

claude Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

amikofalvy commented Feb 19, 2026

Summary

Before (3 independent definitions that can drift)

After (1 definition, everything else derived)

Test plan

Uh oh!

changeset-bot Bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amikofalvy commented Feb 19, 2026

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

PR Review Summary

🔴❗ Critical (0) ❗🔴

🟠⚠️ Major (0) 🟠⚠️

🟡 Minor (0) 🟡

💭 Consider (1) 💭

✅ APPROVE

Uh oh!

claude Bot Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

PR Review Summary

🔴❗ Critical (0) ❗🔴

🟠⚠️ Major (0) 🟠⚠️

🟡 Minor (0) 🟡

💭 Consider (0) 💭

🕐 Pending Recommendations (1)

✅ APPROVE

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-bot Bot commented Feb 19, 2026 •

edited

Loading

vercel Bot commented Feb 19, 2026 •

edited

Loading