From aaf05eb2deaeb3a83a41d2e1027333b8d7120d26 Mon Sep 17 00:00:00 2001 From: Jamie Lee Nichols <10267569+CodingButter@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:42:25 -0500 Subject: [PATCH 1/2] fix(knowledge): load store scope declarations before graph/explorer reads scopeGrants/scopeLabel read the last-resolved declarations, which for a store-only instance stay config-only until an async call resolves them. The server's no-auth/'all' path never did, so the first graph lacked grants and labels. readScopeFor([]) would resolve but also runs checkDeclarations, which changes 'all' route results, so a check-free resolve method is added. Co-Authored-By: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/knowledge-first-graph-grants.md | 6 +++++ packages/core/src/knowledge/index.ts | 16 ++++++++++- .../src/server/handlers/knowledge.test.ts | 27 +++++++++++++++++++ .../server/src/server/handlers/knowledge.ts | 3 +++ 4 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 .changeset/knowledge-first-graph-grants.md diff --git a/.changeset/knowledge-first-graph-grants.md b/.changeset/knowledge-first-graph-grants.md new file mode 100644 index 00000000000..87d1070de7f --- /dev/null +++ b/.changeset/knowledge-first-graph-grants.md @@ -0,0 +1,6 @@ +--- +'@mastra/core': patch +'@mastra/server': patch +--- + +Knowledge graph and explorer routes now include store-declared grants and scope labels on the first request; adds `Knowledge.resolveScopeDeclarations()`. diff --git a/packages/core/src/knowledge/index.ts b/packages/core/src/knowledge/index.ts index dead8e57c10..adce63bfe6e 100644 --- a/packages/core/src/knowledge/index.ts +++ b/packages/core/src/knowledge/index.ts @@ -171,6 +171,18 @@ export class Knowledge extends MastraBase { return this.#runtime.explainAccess(runScopes, target); } + /** + * Reads the store's scope declarations into the ones {@link scopeGrants}, {@link scopeDeclaration} + * and {@link scopeLabel} use, reusing a read from the last 30 seconds. Call it before those when + * nothing else async ran first, e.g. at the start of a browsing request. Checks nothing and grants + * nothing. + * + * @experimental + */ + async resolveScopeDeclarations(): Promise { + await this.#runtime.resolve(); + } + /** * Who the declared rules give a role on one scope: each principal scope address (bound for this * scope's params) with its strongest role, `self` rules left out. `parentAddress` is the @@ -466,7 +478,8 @@ export class Knowledge extends MastraBase { /** * The declaration a scope page was created from, by its `declaration` key (template children * included, e.g. `account:$orgId:$accountId/internal`), for display. Access rules are left out; - * use `explainAccess` for those. `undefined` for an unknown key. + * use `explainAccess` for those. `undefined` for an unknown key. Reads the declarations as last + * resolved, not storage; see {@link Knowledge.resolveScopeDeclarations}. */ scopeDeclaration(key: string): KnowledgeScopeDeclarationInfo | undefined { const compiled = this.#runtime.compiled.declarations.get(key); @@ -491,6 +504,7 @@ export class Knowledge extends MastraBase { * declaration's `$params` filled in from the address's decoded values: `'$orgId policy'` on * `policy:$orgId` gives `'acme policy'` for `policy:acme`. A concrete address's own `displayLabel` * wins over its pattern's. `undefined` when the address matches no declaration or has no label. + * Reads the declarations as last resolved, like {@link Knowledge.scopeDeclaration}. */ scopeLabel(address: string): string | undefined { const match = this.#runtime.compiled.match(address); diff --git a/packages/server/src/server/handlers/knowledge.test.ts b/packages/server/src/server/handlers/knowledge.test.ts index 3aff401f9a7..fd7efef4d66 100644 --- a/packages/server/src/server/handlers/knowledge.test.ts +++ b/packages/server/src/server/handlers/knowledge.test.ts @@ -179,6 +179,33 @@ describe('Knowledge read routes', () => { expect(graph.grants).toHaveLength(4); }); + it("sends the store's declared grants and labels on the first request, before anything else resolved them", async () => { + const { mastra, support, eng } = await setup(); + const store = await mastra.getKnowledge('main')!.getStorage(); + vi.spyOn(store, 'getScopeDeclarations').mockResolvedValue({ + ...declarations, + 'org:$orgId': { displayLabel: '$orgId organization' }, + }); + const graph = await call(GET_KNOWLEDGE_GRAPH_ROUTE, { mastra, knowledgeKey: 'main' }); + expect(graph.grants).toEqual( + expect.arrayContaining([ + { principal: 'role:acme:admin', principalLabel: 'acme admin', target: support.id, role: 'owner' }, + { principal: 'role:acme:admin', principalLabel: 'acme admin', target: eng.id, role: 'owner' }, + ]), + ); + expect(graph.grants).toHaveLength(4); + }); + + it("labels scope pages from the store's declarations on the first tree request", async () => { + const { mastra } = await setup(); + const store = await mastra.getKnowledge('main')!.getStorage(); + vi.spyOn(store, 'getScopeDeclarations').mockResolvedValue({ + 'org:$orgId': { displayLabel: '$orgId organization' }, + }); + const tree = await call(GET_KNOWLEDGE_TREE_ROUTE, { mastra, knowledgeKey: 'main' }); + expect(tree.pages.map((page: { displayLabel?: string }) => page.displayLabel)).toEqual(['acme organization']); + }); + it('sends a signed-in caller only grants from principal scopes it can read', async () => { const { mastra, acme, support } = await setup(declarations); const knowledge = mastra.listKnowledge().main as unknown as Record; diff --git a/packages/server/src/server/handlers/knowledge.ts b/packages/server/src/server/handlers/knowledge.ts index 6cb5801ed98..28d4f486a68 100644 --- a/packages/server/src/server/handlers/knowledge.ts +++ b/packages/server/src/server/handlers/knowledge.ts @@ -184,6 +184,9 @@ async function resolveStore( } const readers = requirePageReaders(); const read = await callerReadScope(mastra, requestContext, instance); + // `scopeGrants` and `scopeLabel` read the declarations as last resolved; this loads the store's. + // Older cores without it compile every declaration from config. + await instance.resolveScopeDeclarations?.(); return { instance, store: await instance.getStorage(), read, readers }; } From 6fcf9a74f1de3ae282c565fd5f1406ceb92a02d4 Mon Sep 17 00:00:00 2001 From: Jamie Lee Nichols <10267569+CodingButter@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:46:57 -0500 Subject: [PATCH 2/2] docs(core): point scopeGrants at resolveScopeDeclarations; name the Studio symptom in the changeset Co-Authored-By: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/knowledge-first-graph-grants.md | 2 +- packages/core/src/knowledge/index.ts | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.changeset/knowledge-first-graph-grants.md b/.changeset/knowledge-first-graph-grants.md index 87d1070de7f..4c01b51486b 100644 --- a/.changeset/knowledge-first-graph-grants.md +++ b/.changeset/knowledge-first-graph-grants.md @@ -3,4 +3,4 @@ '@mastra/server': patch --- -Knowledge graph and explorer routes now include store-declared grants and scope labels on the first request; adds `Knowledge.resolveScopeDeclarations()`. +Studio's Knowledge graph and explorer now show grants and scope labels from store-supplied declarations (e.g. Platform Knowledge) on the first request, not only after another call loaded them. Adds `Knowledge.resolveScopeDeclarations()`. diff --git a/packages/core/src/knowledge/index.ts b/packages/core/src/knowledge/index.ts index adce63bfe6e..887c36b9e0d 100644 --- a/packages/core/src/knowledge/index.ts +++ b/packages/core/src/knowledge/index.ts @@ -187,7 +187,8 @@ export class Knowledge extends MastraBase { * Who the declared rules give a role on one scope: each principal scope address (bound for this * scope's params) with its strongest role, `self` rules left out. `parentAddress` is the * address of the scope page's tree parent, needed for rules that bind through `belongsTo`. Reads the - * declarations as last resolved, not storage. For browsing UIs that draw access between scopes. + * declarations as last resolved, not storage (see {@link Knowledge.resolveScopeDeclarations}). For + * browsing UIs that draw access between scopes. * * @experimental */