0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00

fix(core): Knowledge scope values are one encoded segment (#30019)

Knowledge scope patterns let the last `$` value take the rest of an
address, so `org:acme:viewer` counted as an `org:$orgId` scope. Its
holder then got that pattern's rights on what was meant to be a separate
scope. Raw ids and escaped ids also had more than one spelling.

This makes each `$` value exactly one segment and gives every scope one
canonical spelling.

## What changes

- A scope value can't contain a raw `:`. Ids with `:`, `/`, `#` or `%`
are passed encoded, via the new `encodeKnowledgeScopeId`
(`decodeKnowledgeScopeId` reverses it). Raw forms are refused with a
message naming the helper.
- Agent `scopes` are canonical addresses: `%` is always an escape.
- Memory resource and thread ids are bound encoded (`slack:U123` becomes
`resource:slack%3AU123`). Knowledge takes identity only from the run's
resolved Memory ids, never from `resource:`/`thread:` strings in the run
scopes.
- Patterns of one type with different segment counts no longer overlap,
so `org:$orgId` and `org:$orgId:viewer` can be declared together.
- A stored scope row whose address now matches a different declaration
than the one it was created under gets none of the new declaration's
access: not by exact address, prefix, `belongsTo` lookup or parent-bound
role. Holders of the old declaration's prefix grant still read it, as
before, without a role.

## Existing data

Nothing is rewritten. Ids with a raw colon in the last segment get new
addresses, so a run reaches a new, empty scope, and rows at the old
address stay unreached. Ids with `/`, `#` or `%` were already encoded
and keep their addresses when passed through `encodeKnowledgeScopeId`.
Knowledge is in alpha; this is a breaking change for colon ids.

## Testing

- New tests cover encoded and raw ids, segment counts, stale rows
(exact, prefix, `belongsTo` parent, parent-bound roles) and Memory
identity through `resolveAgentScopes`. Each fails on the commit before
its fix.
- Core Knowledge, storage and agent-scope suites: 412 passed. Server
Knowledge handlers: 48 passed. Typecheck, lint and format are clean.
- A store written by the previous release, read by this one: `/`, `#`,
`%` and literal-escape ids remain readable through
`encodeKnowledgeScopeId`; colon ids move.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

**ELI5:** Knowledge uses labels called scopes to decide who can read
which pages. This change makes each label part match exactly one piece
of the address, and it requires special characters in IDs to be encoded.
This makes access rules predictable, but old alpha data with colons in
IDs may no longer be reached.

## Overview

This change makes each scope parameter match exactly one address
segment. Scope IDs that contain reserved characters must use canonical
encoding. The change is breaking for alpha Knowledge users who have
colon IDs in the last segment.

## Core changes

- **Scope matching** (`declarations.ts`): Patterns match an exact
segment count. A final parameter no longer absorbs raw colons. Raw Agent
scopes are no longer matched. `knowledgeRunScopes` accepts only
canonical addresses that match a declaration, returns them unchanged,
and rejects reserved characters that are not encoded.
- **Overlap rules** (`declarations.ts`): Patterns overlap only when they
share a type, have no conflicting literals, and have equal segment
counts.
- **Encoding** (`scope-address.ts`):
- `encodeKnowledgeScopeValue` and `decodeKnowledgeScopeValue` always
escape `%`, `/`, `#`, and `:`. The `final` argument is removed.
- New experimental helpers `encodeKnowledgeScopeId` and
`decodeKnowledgeScopeId` encode and decode one ID segment. They are
exported from `index.ts`.
- **Memory identity** (`run.ts`): Resource and thread scopes are built
by binding Memory IDs through `knowledgeScopeAddress`. The generated
addresses must match compiled declarations. A mismatch raises
`KnowledgeDeclarationError`. The result is the deduplicated union of raw
and Memory-derived scopes.
- **Stale rows** (`scope-runtime.ts`): A stored scope is current only
when it has no declaration key or its address matches that declaration.
Stale rows are excluded from `belongsTo` parent resolution, final
readable addresses, and `roleOn`. `explainAccess` returns no grants for
a stale target. Materialization rejects a stored scope whose declaration
no longer matches its address.

## Mastra Code and Factory changes

- `knowledge-scope.ts` encodes Factory organization and project IDs
once, as single canonical segments. A host tag of the same type with a
different value is rejected.
- `knowledge-inspector.ts` encodes resource and thread IDs before
calling `readScopeFor`. It no longer uses the local `canonical` helper.
Session tags are unchanged.
- `factory/src/routes/knowledge.ts` encodes organization and project IDs
before building `org:` and `project:` principals.

## Data compatibility

- No stored data is rewritten.
- IDs with a raw colon in the last segment map to new addresses.
Existing rows at old addresses are not reached.
- IDs that contain `/`, `#`, or `%` keep their addresses when encoded.
- Stale rows do not gain access from a new matching declaration. A
prefix grant from the original declaration can still include those rows
in reads, as tested in `legacy-scope-rows.test.ts`.

## Documentation

- Scope declaration docs say each `$param` matches one segment. They
describe compatibility effects for alpha scopes and the new overlap
rule.
- Memory scope docs describe `encodeKnowledgeScopeId` and
`decodeKnowledgeScopeId`. They state that alpha scopes with a raw colon
in the last segment are not migrated.
- `explainAccess` docs describe `runScopes` as canonical addresses.
- A changeset marks a minor `@mastra/core` release. Changesets for
`@mastra/code-sdk` and `@mastra/factory` are patch releases.

## Tests

- New and updated tests cover encoded and raw IDs, segment counts, stale
rows, and Memory identity through `resolveAgentScopes`.
- A new helper, `agentRunContext`, is used by test files.
- The author reports 412 passing core Knowledge, storage, and
agent-scope tests. The author also reports 48 passing server Knowledge
handler tests, and clean typecheck, lint, and format. These results are
not verified here. CI status is not available.

## Scope of change

- Files changed: 24
- Lines added: 549
- Lines removed: 116
- Review severity counts: not available
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: remy-builder[bot] <324360501+remy-builder[bot]@users.noreply.github.com>
This commit is contained in:
Tyler Barnes 2026-11-12 14:52:04 -07:00 • committed by GitHub
commit 175b4b5194
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
24 changed files with 549 additions and 116 deletions