package PBS references and expose paginated MCP reads

This commit is contained in:
2026-09-29 08:48:33 +01:00
parent 58f11a8123
commit feb57c5298
23 changed files with 738 additions and 21 deletions
@@ -323,3 +323,36 @@ The current Studio direction is:
4. the compiler should use explicit abstractions such as `StdlibEnvironment` and `StdlibModuleResolver`,
5. stdlib interface modules are parsed with the normal PBS parser and validated in interface-module mode,
6. reserved attributes such as `[Host(...)]` are extracted as compile-time metadata for later lowering.
## 13. Installed Language and SDK Reference Bundle
The PBS frontend distribution MUST provide local, indexed documentation through
the frontend reference-provider contract. This packaging does not create a new
normative specification: the numbered PBS documents in their owner directory
remain authoritative, and the quickstart/example remain informative.
The build MUST generate the reference index from owner-maintained sources:
- this directory's numbered specifications and README quickstart;
- the frontend's example manifest, PBS source and barrel;
- the actual packaged SDK `.pbs` and `.barrel` files, including their documentation.
Generated copies MUST NOT be edited independently. SDK declarations MUST NOT be
rewritten to manufacture a documentation-only API. The index MUST contain stable
reference identities, titles, kinds, packaged-resource identities, content hashes
and applicable SDK major/target. The loader MUST reject missing/corrupted indexed
content instead of advertising unreadable references or consulting a checkout.
For the current distribution, SDK/example selection is Game / major 1. The general
PBS specifications remain available for other selections, but Game SDK 1 references
MUST NOT be presented as another SDK version or target. An absent SDK reference
set MUST be explicit to consumers.
Language, compiler, SDK and index-schema versions remain independent. General
specification references use an unknown release version when owner release
metadata is absent; SDK-associated references identify the installed SDK major.
Content hashes identify the packaged texts, not a semantic language release.
Conformance MUST include reading all indexed references from installed JARs outside
the repository and compiling the shipped example against the installed SDK. No
network access or source checkout may be required by that reference-read path.
@@ -2,6 +2,73 @@
This directory contains the normative PBS specification set.
## Installed Quickstart (Informative)
This guide and the numbered specifications are packaged with the PBS frontend.
They describe the installed distribution, not a promise of a numbered language
release. A spec's `Draft v1` status is not the compiler version or SDK version.
The project manifest selects the SDK major with `stdlib`; current packaged
Game SDK resources use major `1`. Unknown language/compiler versions remain
unknown in Studio's context.
For an external coding agent:
1. Request `studio_project_context` for the absolute root of the open project.
2. Read `pbs:quickstart`, `pbs:spec:3` (syntax), `pbs:spec:4` (static semantics)
and the relevant SDK reference IDs returned in that context. Continue pages
until `nextOffset` is null. References are IDs, not filesystem paths.
3. Inspect the project and its dependencies before changing source. Only edit
the project's editable scope, excluding read-only SDK/external libraries.
4. Use the installed LSP and compiler to check changes. When the corresponding
MCP tools are available, acquire project control after the developer's DEV
grant, then use the advertised language/build tools. Documentation reads do
not require that grant. Missing tools/capabilities must not be assumed.
5. Build and test small changes. Runtime execution also requires a compatible
configured runtime; reading references does not install one.
### Small Game Project
The installed example has three separately indexed files:
- `pbs:example:game:1:prometeu.json`: a Game manifest with `language: pbs`,
`stdlib: 1` (serialized as a string), and no external dependencies;
- `pbs:example:game:1:src/main.pbs`: `[Init]` and `[Frame]` functions drawing a
moving rectangle through `Gfx` and constructing colors through `Color`;
- `pbs:example:game:1:src/mod.barrel`: the module's public declarations.
Copy these reference texts to the corresponding paths only when creating that
example in your editable project. The example is compiled in the test suite;
it is not a complete game or a claim that every requested gameplay abstraction
already exists. If a project has no external dependencies, no registry is needed.
For dependencies, follow the installed compiler's manifest/registry requirements.
PBS source lives under `src` for the installed provider. Functions use `fn`,
typed parameters and `->` return types. `let` declares a local binding;
`declare global` declares persistent global state. Imports name exports and a
module address, for example `import { Gfx } from @sdk:gfx;`. A `mod.barrel`
describes a module's public surface. Read the syntax/static-semantics chapters
for exact rules rather than inferring compatibility with another language.
### SDK Navigation and Limits
`pbs:sdk:game:1:sdk/gfx/main.pbs` exposes the actual installed Gfx source,
including documentation comments and signatures. Its `mod.barrel` reference
defines exports. Equivalent references exist for `sdk/asset`, `sdk/composer`,
`sdk/input`, `sdk/log`, and `core/color`. Read those interfaces before calling
them. Game SDK 1 does not currently ship `audio` or `core/math` modules.
Ordinary game source uses public services such as `Gfx`; it must not manufacture
host bindings or mutate SDK declarations. Asset/composer workflows require their
real asset/scene data and runtime capabilities. Reference availability does not
guarantee those project resources exist. SDK or tooling limitations should be
reported for separate work, not patched in read-only dependencies.
The reference index is generated from these owner-maintained documents and the
frontend's SDK/example resources. The index schema revision is not a language
version. Source hashes bind texts to the installed bundle; no repository checkout
or network is needed to read them. The numbered specifications remain normative;
this onboarding section and example are explanatory, not a second specification.
## Purpose
Specs define the official PBS language/frontend contract.
@@ -184,7 +184,8 @@ Reference reads take an opaque ID from that index, not a path or arbitrary URI.
Offset defaults to 0; limit defaults to 4000 and accepts 1–16000 Unicode code
points. A page returns referenceId, offset, total, text and nextOffset (null at
end). Invalid pagination fails; unknown/traversal-like IDs cannot escape the
index. Installed packaging and real provider resolution are steps 17–18.
index. Installed reference content is resolved through the frontend's owner-maintained
reference provider, not a Studio-maintained language specification.
### 5.1 Manifest and Provider Resolution
@@ -230,9 +231,44 @@ symlink targets. SDK entries are always read-only; packaged SDK resources need n
have filesystem roots. Scope metadata does not sandbox an external agent's own
filesystem tools; the developer remains responsible for those tools and Git.
Paths in MCP results are absolute filesystem strings, not `file:` URIs. Until
step 18 packages the owner-maintained index, references/reference IDs are empty
with `DOCUMENTATION_UNAVAILABLE`; no guessed path or reference is advertised.
Paths in MCP results are absolute filesystem strings, not `file:` URIs.
### 5.2 Installed References and Pagination
An installed frontend MAY implement `FrontendReferenceProvider` through
`FrontendProvider.documentation()`. That compiler-side contract supplies indexed,
owner-maintained texts for an SDK major and project target. It does not depend on
Studio API or MCP. Studio projects these into neutral reference descriptors;
full texts MUST NOT be included in project context. Reference IDs are namespaced
by language (`<languageId>:`), unique within the selected project index and opaque
to callers. Studio MUST NOT interpret an ID as a filename, URI or URL.
PBS packages its numbered specifications and informative quickstart from their
owner directory, plus a compilable Game example and actual SDK sources/barrels.
A build-generated index binds these texts to the installed frontend using content
hashes. Distribution-only reads MUST work without a checkout or network. SDK and
example references identify their SDK major and target; unsupported selections
MUST NOT silently reuse another SDK/target. Numbered spec/draft revisions and the
reference-index schema revision MUST NOT be reported as language/compiler versions.
`studio_reference_read` is authenticated but does not require a control grant or
task. It resolves the explicit open root and its current saved manifest selection
on every read. Changing SDK/target can invalidate previously advertised IDs.
Only IDs in that project's installed index can be read, including when other
languages/providers are installed globally. SDK and external-library texts remain
consultable, not editable through this surface.
Pagination counts Unicode code points: an astral character occupies one offset,
not two UTF-16 units. Offset 0/limit 4000 are defaults; limit MUST be 1–16000.
An offset equal to total returns empty text and null nextOffset. Offsets beyond
total, negative offsets, nonintegral values and integers beyond the implementation's
signed 32-bit range are invalid parameters, never wrapped/truncated to another page.
Missing or unreadable provider documentation yields `DOCUMENTATION_UNAVAILABLE`
limitations, not promised references. An uninstalled primary language yields
`UNSUPPORTED_LANGUAGE` for reference reads; an available index without the requested
ID yields `REFERENCE_NOT_FOUND`. Closed projects yield `PROJECT_NOT_OPEN` before
reference lookup. These failures do not grant/revoke task authority.
## 6. Image Contract
@@ -258,7 +294,8 @@ authentication, Origin, endpoint/method/version handling, tool dispatch, malform
or oversized input, closure, restart and old-token rejection. Provider doubles
exist only in tests. Composition starts/closes transport with Studio.
The production registry composes `studio_project_context` as of step 17; other
The production registry composes `studio_project_context` and `studio_reference_read`
as of step 18; other
tools are advertised only when their functional handlers are connected.
DEV configuration-copy stays unavailable until step 21. Passing this transport
gate is not the phase 3 or final external-agent acceptance gate. API/Core and