package PBS references and expose paginated MCP reads
This commit is contained in:
+33
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user