Skip to content
AggregaAggrega
Select language: English

The workspace boundary

A workspace is the directory tree a project root marks — the root your configuration’s workspace: block sits in, the one --workspace-root names, the folder an editor opened, or the one an assistant’s server was started over. Everything Aggrega reads and writes on its own account is held to that tree, except where you, or the workspace configuration, name a place outside it. A symbolic link inside it can point anywhere on the machine, so a link is never taken as part of the workspace just because it sits there: what counts is where it leads.

This page states the rule whole. The pages for each surface — the command line, the language server and the assistant tools — say how their own requests meet it.

What lies inside the workspace

A path is inside the workspace when the deepest part of it that exists, with its links followed, is the workspace root or lies beneath it — the root’s own links followed the same way, so a workspace you reach through a link of its own still holds everything beneath it.

A root you open through a link is the workspace the link leads to. Whether the folder you open is itself a link or is reached through one above it, Aggrega lists, reads and writes exactly what it would in the workspace the link leads to — its Releases, its documents, its lockfiles — and judges every link inside it the same way. Every path in an answer is still spelled from the root as it was given — the folder an editor opened, the --workspace-root you typed, the directory your shell says you are working in — so what you are shown matches the paths you are working with.

That one reading covers every kind of path:

  • Where a path leads decides it, not how it is spelled. ./shared/app.yaml is outside when shared is a link to a directory elsewhere, though every part of it is written inside the workspace. A request parameter can still ask for a spelling of its own — a path relative to the root, say — and its own page says so; that is a rule about the parameter, not about the boundary.
  • A path that does not exist yet is judged by the directories on the way to it. A file a build is about to create beneath a dist that is a link leading out is outside before it is written.
  • A link that leads nowhere, or round a loop, is not something that exists. The directory holding it is judged instead, and nothing is followed to find out where the link was meant to go. Where such a link stands exactly where a file is about to be created, the place it points to is checked too, since that is where the file would land.
  • A link to somewhere else inside the workspace is followed as usual. Only a link leading out is held.

The rule judges where a path leads on disk and nothing else. It reads no value and infers nothing from a name.

What happens to a path that leads out depends on what kind of path it is. There are three outcomes.

Listed as not read

Where Aggrega lists what the workspace holds, a link leading out is not read, and the listing says so. The Releases an editor offers to choose from, the entity index and the completions and candidates an editor draws from it, and an assistant’s list-releases and list-entities do not search a directory outside the workspace or read a file outside it, whatever that file declares — so an entity your editor shows under such a link is not listed as the workspace’s own. The Release listings and the entity listings name every such link by its own place in the workspace, never by where it leads: unreadLinkedDirs and unreadLinkedFiles on the language server, unread_linked_dirs and unread_linked_files on the assistant tools. A link to a directory your configuration lists under catalog_dirs, or to a directory beneath one, or to a Release it names, is not named: the configuration has reached that place — a listed directory is read with everything beneath it — as the exceptions below describe. A .gitignore that is a link leading out is not read either, so a file elsewhere on the machine never decides which of the workspace’s documents are searched. A workspace configuration file that is a link leading out is named among the files not read too: these listings still answer for that workspace, read with nothing configured, while every request the configuration decides halts, as the workspace’s own configuration below describes.

Refused

A path a request names, where the caller is not the machine’s owner typing it, is refused. Apart from the exceptions below, every path an editor’s request to aggrega serve names for the server to read or write, and every path an assistant names to a server reached over HTTP, has to lead inside the workspace; one that leads out is refused with nothing read or written, and the refusal names the parameter, as each surface’s page sets out. The document edit is refused this way on every surface, the command line included — see The document edit stays inside.

Halted

Where an operation would read or write through a link leading out on its own account, it stops. These are the paths the product works out for itself rather than paths you named, and passing over one in silence could change what a build means, so each stops the operation, names the link and where it leads, and leaves the place the link points to exactly as it was:

  • What a lookup reads — a document beneath a catalog directory, or beside a Release that names its Aggregate or its Manifest by identity, or beside a Manifest that names the Manifest it extends that way. The Release or the Manifest the operation was named is not one of those documents: it was read where it was named — see A Release or a Manifest named through a link. A lookup that skipped such a link could resolve another entity of the same name from a later directory in its place, so a build, a pull, a validation, an inspection that reads the catalog, a lint of one Release or of the whole catalog, and the editor’s and an assistant’s requests that build, preview, graph, validate, lint or describe a Release all stop before anything is resolved or checked: E0321.
  • A Release’s lockfile — read beside the Release for the pins a build, a pull, a validation, a lint, an inspection, aggrega cache prune and the editor’s and an assistant’s requests resolve against. It is held where it is read exactly as where it is written, so a lockfile that is a link leading out stops each of them rather than lending them pins kept elsewhere on the machine: E0321.
  • A file read beside an entity — the other documents in the directory of an entity you pin or publish, read to tell whether another entity shares that directory, and the built .wasm a Plugin entity in a catalog directory is loaded from. Each is read only from inside the directory the entity’s own document was read under: the workspace, a catalog directory you named outside it, or the directory of a document you named outside it. So one that is a link leading out stops aggrega pin, aggrega push (a dry run included), a pull that pins and the editor’s and an assistant’s pin and publication — a document left unread could be the entity in the way — and stops a build or a pull that loads the plugin rather than running bytes kept elsewhere on the machine: E0321.
  • The artifact cache — everything Aggrega reads from the cache under artifact_cache_dir: a cached entity, plugin or library and the manifest beside it, a source archive and its metadata, a pinned external input, a signature bundle and a registry’s local search index, and every workspace entry aggrega cache status, aggrega cache prune and aggrega cache clear list. The cache is read only from inside the cache directory, the place it is written to, so anything in it that is a link leading out of that directory — to elsewhere in the workspace as much as anywhere else — stops a build, a pull, a validation, a search, each of the three cache commands, and the editor’s and an assistant’s requests that read the cache, rather than handing them bytes kept somewhere the cache does not own — content checked against a recorded digest included, since a digest says what the bytes are, not where they may be read from. The deprecation notice aggrega inspect prints, which decides nothing, is left out. A prune or a clear meets one of the cache’s own directories that is such a link, or a cache directory that is itself a link leading out of the workspace, as the removal it would be, with E0320, before it lists anything: E0321.
  • A repository a source fetches — the checkout a pull archives for a git-repository source. The checkout is a directory of its own, so a link the repository carries is archived as what it points to only where that lies inside the repository; one leading out of it, which could reach any file on the machine running the pull, stops the pull naming the link and where it leads, with nothing cached — module_subdir itself included, where it is such a link: E0321. The checkout is gone once the pull stops, so the message names the link by its place in the repository, and the repository and the revision the source names. A module_subdir that climbs above the repository as written is refused before the repository is fetched, so nothing beside the checkout is read: E0307.
  • The files of a directory you import — aggrega import, the assistant’s import tool and the session’s aggrega/import, given a directory, read the files of it the importer’s file patterns select. The directory is a root of its own wherever it lies — see A directory you import — so a link among those files leading out of it, or a link to a directory leading out of it, stops the import naming the link before any file of the directory is read: E0321.
  • The workspace’s own configuration — every .aggrega-config.yaml from the root down to the directory a command runs in, and a pipeline’s .aggrega-config-append-ci.yaml beside any of them. Every command that reads the configuration, the language server and an assistant’s tools read it before anything else, so one of these files that is a link leading out stops each of them there rather than letting them run on a configuration made from whatever remained: E0321. The aggrega commands that never read it — version, help, completion, explain, get-schema, scaffold drafting a starter document, skills list, plugin run-local, plugin sync, auth token and logout — run as usual, with a warning naming the link. scaffold --example reads it, for the default registry and the signature policy, and stops there as every other reader does. The language server, and an assistant’s server speaking over its own streams, still start over such a workspace, so that what it holds can be listed: the Release and entity listings answer, read with no catalog directory and nothing else configured, and name the file among the links not read. Every other request the configuration decides — a build, a preview, a graph, a validation, a lint, a description, the effective configuration, the default Release — halts with E0321 naming the link, and so does an assistant’s server asked to listen over HTTP, whose address and authorization the configuration would have set.
  • What an operation writes or removes — a build’s output directory, its boundary directories and every file written there, the trace; a Release’s lockfile and the plugin trust record beside it; an entity.lock; the workspace configuration file a command writes; the artifact cache and each part of it a pull fills or aggrega cache clear and aggrega cache prune empty; the drafts an import writes and the Plugin entities aggrega plugin gen-catalog writes; and the .aggrega/active-release marker an editor records a default Release in, which the language server writes for it. A dist that is a link would otherwise turn “rebuild the output” into deleting a directory somewhere else on the machine: E0320.
  • What a document names by a path — see A reference a document writes: E0324.
  • The content an entity declares — a source: or an $import: whose path passes through a directory that is a link leading out of the entity’s own directory, which a publication would otherwise carry under a name inside the entity: E0304.

These hold whoever started the operation — the command line, an editor, or an assistant on either transport — because the path is the workspace’s and the product’s, not the caller’s.

A reference a document writes

A Release and a Manifest can name another file by a path: a Release’s aggregate: and manifest: written as ./… or ../…, its extends:, a Manifest’s extends: written as a path, and a Release’s parameters: { $import: … }. A document in the workspace reaches only files inside the workspace that way — a path that climbs out as written is refused, and so is one that stays inside as written but meets a link leading out on the way. Nothing is read from the file either names.

A workspace you cloned carries its author’s references, so confining what you name while following whatever a document then leads to would leave the boundary one ../ away. Where a document needs an entity kept elsewhere, it names the entity rather than a file — aggregate: payments — and the workspace configuration lists the catalog directory holding it. A name is looked up, not followed, so it is never refused here.

A Release or a Manifest that lies outside the workspace, admitted because you named it, reaches only files in its own directory — see An exception reaches the directory it names, and no further.

The exceptions, and why each is one

A path in one of these classes is honoured where it leads, inside the workspace or not. Each is a class of path rather than a list of places, and each is an exception for a reason of its own.

  • What the workspace configuration names. Its catalog directories — catalog_dirs and catalog_dirs_append, for the workspace or for a Release under workspace.releases — the Release files keyed under workspace.releases, build.authoring_release, a plugin attachment’s local .wasm and the files under its with.sources, mcp.tls.cert_file, mcp.tls.key_file, mcp.authorization.jwks_file, a registry’s pinned trust root, and an artifact_cache_dir that climbs out of the workspace root. Naming a path in the configuration is the deliberate way a workspace reaches outside itself: it is written down once, kept with the project, and read by anyone reviewing it. The workspace’s conventional catalog directory counts as named when the configuration lists it or you pass it with --catalog — or lists, or you pass, the place it leads to, in any spelling, or a directory above that place, which then reads what lies there once, through the directory you named. Read only because it is there, it is the workspace’s own content, so a catalog that is a link leading out of the workspace is not read until you name it or where it leads.
  • A path you type on the command line. aggrega build --release ../other/release.yaml, --catalog /srv/shared-catalog, --output-dir, a file to validate, lint, pin or publish: each is used where it leads — the document edit apart, below. You own the machine the command runs on and can already read and write anything you would type, so holding you to a directory would buy nothing.
  • A path an assistant names over the process’s own streams. A client that launched aggrega mcp on your machine runs as you, and its host usually gives it file and shell tools of its own, so a path it names is honoured as if you had typed it — see The two assistant transports.
  • The product’s machine-wide stores — the global configuration file, the compiled-module store, the plugin descriptor cache, the documentation bundle and the registry credential store. They belong to the machine rather than to any workspace, so no workspace holds them.
  • A file or a directory picked in a dialog, read where it is. An editor sends the key file or trust root of a registry registration as an absolute path, the description aggrega/import converts — a file, or a directory whose files the importer reads — and the module aggrega/pluginGenCatalog generates an entity for with the overlay beside it. A person chose each one, wherever they keep it. They are only read: nothing a request writes goes to a path chosen this way. A directory picked this way is held to itself, as every directory you import is.
  • A document your editor holds open. Validating it, asking for its diagnostics or dropping them, hovering, completing, resolving, and finding references and implementations in it are answered from the content the editor sent, so no file is read at the path that names it, and the path is never refused for where it leads. A request that does read the document from disk is the refused kind above.

The command line’s typed paths and the machine-wide stores are never judged at all; the others are let through by their class, never by the request that happens to carry them.

An exception reaches the directory it names, and no further

A directory you named outside the workspace is a root of its own for everything read or written beneath it. The directory itself is used as you named it — one that is a link is followed to where it points — and a link beneath it leading out of it is held exactly as a link inside the workspace is: not read in a listing, and halting a lookup or a write. So a catalog directory you list outside the workspace, an output directory you pass to aggrega plugin gen-catalog or aggrega import, and an artifact_cache_dir that climbs out of the workspace each hold what is beneath them to themselves. Where a directory you named lies inside the workspace, the workspace is the root — a directory you import apart, which is a root of its own wherever it lies.

A directory you name is resolved against the folder you run in before anything is placed beneath it. An output directory you pass to aggrega import, typed relative, is the folder of that name in the folder you run the command in, and a drive you name bare on Windows — D: — is the current folder on that drive. The directory is made a full path first and every file is placed beneath that full path, so a file whose name opens with a separator, \notes.txt say, lands inside the directory you named rather than at the top of the drive, and the directory the command reports is the one written to.

A Release or a Manifest you named outside the workspace is the same rule read for a file: its own directory is the root, so what it names by a path — and what every Release its extends: chain leads to names — must stay inside that directory. A Release kept beside its Aggregate and Manifest builds from anywhere; one in the usual releases/ layout, naming ../aggregates/app.yaml, is built from its own workspace instead.

A Release you name through a link is read where the link leads, and resolved where you named it. Typed as --release release.yaml where release.yaml is a link to a file kept elsewhere — or named that way under workspace.releases, or as build.authoring_release — the Release is read from the place the link leads to. The Aggregate and the Manifest it names, by identity or by a path, are looked for beside the link, in the directory you named it in, and held to that directory’s root: the workspace, or the directory itself where it lies outside the workspace. Its lockfile is read and written beside the link too, never where the link leads. The Release is not one of the documents its own lookup meets beside it, so it never stops that lookup; another Release kept beside it that is a link leading out still does. A Manifest you inspect on its own through a link is read and resolved the same way.

The artifact cache directory is a root of its own, wherever it is. Everything the cache holds is written, read and removed only inside the cache directory, so one of the cache’s own directories, or a file in one, that is a link leading out of the cache directory is held — even where it leads elsewhere inside the workspace — while one leading elsewhere inside the cache directory is followed. Where the cache directory itself lies is read from how its value is spelled. Written inside the workspace root — the default .aggrega/cache included — it is the workspace’s own directory: a cache directory that is a link to elsewhere inside the workspace is followed, and one leading out of the workspace is refused, for reading as for writing. Written climbing out (../shared-cache), it is a directory the configuration names, read and written where it leads.

A directory you import

A directory you import is a root of its own, wherever it is — inside the workspace as much as outside it, which is where it differs from every other directory you name inside the workspace. aggrega import, the assistant’s import tool and the session’s aggrega/import hand the importer each file of the directory under its place in that directory, so what they hand it is read only from inside the directory. What is judged is what the import would take something from: a link to a file a pattern of the importer selects — any importer’s, where the format is recognised rather than named — and a link to a directory, which is never entered. One of those leading out of the directory is refused before any file is read, even where it leads elsewhere inside the workspace, while a selected link to a file elsewhere inside the directory is read where it points, under the link’s own name. A link to a file no pattern selects is neither judged nor read. The directory itself is used as you named it, one that is a link followed to where it points.

The document edit stays inside

aggrega edit-document, the language server’s document edit and insertion point, and the assistant’s edit-document and insertion-point act only on a document the workspace carries. A document outside the workspace, as written or through a link leading out of it, is refused on every surface with nothing read or written — including where a path you name is otherwise honoured.

The two assistant transports

aggrega mcp serves the same tools two ways, and the boundary differs between them because the caller does.

  • Over the process’s own streams, the client launched the server on your machine, so a call is you typing on the command line: a path argument may be absolute and may lie outside the workspace, a call may name its own workspace_root and catalog_dirs, and the tools that run an aggrega command in a separate process are offered. Only the path a call names is honoured as named. What the operation then reads and writes on its own account is held as it is at a terminal: a listing does not read through a link leading out, a reference a document writes does not leave the workspace, and a write does not go through a linked output or cache directory. Workspace content can steer what an assistant asks for, so on a host where these tools are its only reach into your files, a document in a workspace you cloned can still lead it to name a path outside the workspace and have it read or written; what an assistant can do without asking you first is where you set how much it does unprompted.
  • Over HTTP, the caller does not own the machine the server runs on. The workspace is the one the server was started over and is fixed for its life; every path argument is held inside it, judged as above; a call naming workspace_root or catalog_dirs, or selecting a signing key held on the host, is refused; and the tools that run an aggrega command are not offered. A refusal names the argument and quotes a relative value as sent, but names neither the workspace root nor where a path would have led.

When something is refused or halts

What you seeWhat to do
A listing names a link among those it did not readReplace the link with a copy of what it leads to; or, for entities kept elsewhere, list the directory the link leads to under catalog_dirs; for a Release kept elsewhere, name it under workspace.releases or as build.authoring_release.
E0321, a read through a link out of a catalog directory or a Release’s directoryList the directory the link leads to as a catalog directory, or pass it with --catalog, rather than reaching it through a link beneath one; or replace the link with a copy. Where the link is the conventional catalog itself, list catalog or the directory it leads to, or pass either with --catalog.
E0321 on a Release’s lockfileRemove the link and pull the Release again, which writes a fresh lockfile beside it. A lockfile has no other place.
E0321 on a file beside an entityReplace the link with the file itself: move a document that is an entity into a directory of its own, and lay the built .wasm beside its Plugin entity rather than a link to it.
E0321 on a configuration fileReplace the link with a copy kept in the workspace. A configuration shared between workspaces is read by naming it as the global configuration file, with --config or AGGREGA_CONFIG, beneath each workspace’s own files.
E0321 on the artifact cacheRemove the link; a pull fills the cache again. To keep the cache somewhere else, set artifact_cache_dir to that directory, written relative to the workspace root (../shared-cache), rather than linking it.
E0321 on a link in a fetched repositoryThe link is committed in the repository the source names — the message names it by its place there: change it there — point it inside the repository, or commit the file itself — and name the revision that carries the change.
E0321 on a link in a directory you importKeep the file itself in the directory rather than a link to it, or import the directory the link leads to. A directory you import is read only from inside itself, wherever it lies.
E0307 on a module_subdirName a directory inside the repository: the value may descend beneath the repository’s top but may not climb above it.
E0320, a write or removal through a linkRemove the link the message names, or make it lead somewhere inside the directory the message names, and run the operation again. Nothing in your entity files causes it.
E0324, a reference leading outName an Aggregate kept elsewhere by its metadata.name and list its catalog directory; keep a Manifest, a Release an extends: names and a parameters file inside the workspace — or, for a document you named from outside, in its own directory; or open the workspace at a directory holding both documents.
E0304, content through a linkReplace the link with a copy of what it leads to, inside the entity’s own directory.
A language-server request refused for a path leading outSend a path inside the workspace, relative to its root. A Release kept outside the workspace is reached by naming it in the configuration, under workspace.releases or as build.authoring_release, and naming in the request the link inside the workspace that leads to it — the place the Release listing offers it at.
An assistant call over HTTP refused for a pathSend a path relative to the root of the workspace the server serves; where the refusal offers the relative spelling of an absolute path, send that.
A document edit refusedEdit a document the workspace carries; a link to a document elsewhere is not edited through.

See also

  • Configuration — where each of the settings above is written, and how a relative path in it is resolved.
  • aggrega serve and aggrega mcp — each request and tool, and which of its parameters name a path.
  • Fatal halts — the full entry for each condition above.