feat(pbs): resolve editorial chains and expose read-only external sources
Intrepid/Prometeu/Studio/pipeline/head Build started...
Test / Build skipped: 16, passed: 838
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-07 09:00:31 +01:00
parent d0737df0ac
commit 967b9ec598
38 changed files with 1856 additions and 42 deletions
@@ -537,3 +537,22 @@ The current PBS design direction is:
10. `declare host` remains reserved to stdlib/toolchain interface modules.
11. Reserved attributes such as `[Host(...)]` are compile-time metadata, not runtime objects.
12. The compiler consumes `Host` metadata to produce runtime-facing host-binding artifacts defined elsewhere.
## Editorial exposure of external sources
SDK/core remain reserved bundled sources. Editorial navigation MUST NOT extract
or copy them into a project or disk cache. Compiler-known dependency sources,
including those under `.workspace`, and SDK/core are exposed as read-only external
documents with revision-consistent text, ranges and frontend semantic context.
Hover and continued definition use that retained context. Compilation, module
admission, ABI and linking rules are unchanged. See Compiler Spec 23 §8.3 and
Studio Spec 11 for the consumer protocol and atomic write restrictions (DEC-0062).
PBS project hover, definition, completion and signature help MUST share receiver
type resolution using PBS expression parsing and semantic overload rules. Coverage
includes function/method chains with known return types, nested call arguments,
explicitly typed and inferred variables, parentheses, completion after a trailing
dot and signature help during incomplete arguments. An unrelated parse error MUST
NOT invalidate a recoverable receiver. Unknown or ambiguous receivers MUST NOT
invent a type or overload. Indexing/operator-produced receivers are outside the
new coverage; existing behavior MUST NOT regress.
@@ -356,3 +356,13 @@ 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.
## Editorial exposure of external sources
SDK/core remain reserved bundled sources. Editorial navigation MUST NOT extract
or copy them into a project or disk cache. Compiler-known dependency sources,
including those under `.workspace`, and SDK/core are exposed as read-only external
documents with revision-consistent text, ranges and frontend semantic context.
Hover and continued definition use that retained context. Compilation, module
admission, ABI and linking rules are unchanged. See Compiler Spec 23 §8.3 and
Studio Spec 11 for the consumer protocol and atomic write restrictions (DEC-0062).
@@ -272,7 +272,17 @@ Absent editor capabilities MUST have deterministic fallback behavior at tooling
3. host protocols that can represent unsupported operations SHOULD do so explicitly;
4. and absent editor capability MUST NOT be reported as a compiler failure.
When a frontend exposes definition or navigation, each returned location MUST identify a compiler-known physical source file. A resolved symbol without a physical file MUST produce an empty definition response. Tooling MUST NOT require virtual documents, untitled buffers, or synthetic URIs for this capability.
When a frontend exposes definition or navigation, each returned location MUST identify a compiler-known source in the analyzed revision. Editable main-project locations use `file:`. Bundled SDK/core and ordinary dependency sources use server-issued `prometeu-source:` identities for consumers that negotiate external-source support. Ownership, not physical containment or `SourceKind.PROJECT`, determines editability. Clients without support receive only editable physical project destinations; absent frontend support retains the empty fallback. This explicitly supersedes the earlier physical-only definition policy (DEC-0062).
`FrontendLanguageService.supportsExternalSources` and `sourceDocument` are optional,
with false/empty defaults. `FrontendDefinitionLocation.source`, when present,
contains the known source's exact text, origin, name, language, read-only ownership
and opaque frontend context. Compiler contracts do not mint session URIs; that is
the project host's responsibility. The content digest is not an SDK version.
External source snapshots MUST retain the exact analyzed text, source origin and frontend semantic context together. Declaration offsets and UTF-16 protocol positions MUST be calculated from that text. The frontend owns hover and continued definition inside external documents; adapters MUST NOT resolve language semantics. SDK/core MUST remain bundled without editorial extraction. Unknown, expired, unreadable or unauthorized identities MUST report unavailable without arbitrary path fallback.
External URIs are scoped to a project-server session and a content revision, not an SDK semantic version. A project-owned registry retains snapshots per consumer, independently of transport connections. Last release or project shutdown releases text and semantic context together. Reconnection MUST revalidate before queries resume; changed revisions require fresh navigation, never old positions applied to new text. One consumer closing MUST NOT invalidate another. All edit proposals touching an external source, including physical aliases, MUST be refused atomically. References, workspace symbols, document links and hierarchies retain their existing physical scopes; external navigation does not expand them.
When a frontend exposes find-references, each returned usage or declaration location MUST identify a compiler-known physical source file. A cursor offset whose definition response is empty MUST produce an empty references response. Host `includeDeclaration` MAY add the canonical declaration location only when that declaration is a compiler-known physical source file; it MUST NOT invent a virtual, untitled, or synthetic location.
@@ -246,7 +246,7 @@ for one fixed port. The public LSP configuration default remains unchanged for
other hosts. A manifest language change requires reopening that project's server;
the adapter MUST NOT send queries to a server bound to another language/root.
Each query uses a short-lived client connection. For document requests, the
Each query uses a short-lived client connection. For physical document requests, the
adapter opens exactly the saved UTF-8 text and waits for that connection's
published diagnostics before issuing the semantic query. Other dependency files
are read from disk by the existing compiler bridge. A fresh connection prevents
@@ -266,14 +266,54 @@ Core bounds the request worker wait to 12 seconds. Documents are limited to 4 Mi
of UTF-8 and task-local hierarchy state to 1024 items. These are adapter resource
guards, unrelated to the runtime's deterministic frame/watchdog semantics.
Document URIs must resolve to known physical project/dependency source files.
Document URIs must resolve to known physical project/dependency source files or to an external identity owned by the current task and project.
Symlink targets are canonicalized before admission. External sources may be
queried, but edit-producing queries on read-only roots are rejected. Every URI in
returned workspace-edit proposals is checked against the same editable/read-only
scope; an unsafe proposal is rejected as a whole. File-operation edits and
executable commands are not offered; `workspace/applyEdit` is always refused.
No query writes a file. Virtual SDK declarations may not have physical definition
locations in the existing LSP; indexed SDK references remain available instead.
No query writes a file. `readExternalSource` reads the exact registered external
revision; hover and definition on its URI use the retained frontend semantic
context. Indexed SDK reference tools remain separate and available. MCP needs no
VS Code connection and MUST retain its consumer across short-lived query sockets.
Task return/cancellation releases that task's external uses; project shutdown
invalidates all identities. Cross-task/project replay is refused.
### External-source protocol (DEC-0062)
Initialize negotiates `capabilities.experimental.prometeuExternalSources: true`;
the server advertises the same flag only when supported. External definitions use
`prometeu-source:` URIs minted by the project host. A descriptor carries `uri`,
`revision` (content digest), `origin`, `name`, `languageId` and `readOnly: true`.
Locations carry ordinary LSP UTF-16 ranges over that exact source text.
The `prometeu/readExternalSource`, `prometeu/retainExternalSource`,
`prometeu/releaseExternalSource` and `prometeu/revalidateExternalSource` requests
carry `uri` and a server-issued `consumerId`. Initialize returns that identity in
`capabilities.experimental.prometeuExternalConsumerId`. Reconnecting clients pass
it as `initializationOptions.prometeuExternalConsumerId`; MCP also requests
`initializationOptions.prometeuExternalPersistentConsumer: true` on first use.
`releaseExternalSource` with `uri: null` releases the consumer and all its sources.
A read or explicit retain acknowledges a navigation result; unacknowledged results
are released when the socket closes. MCP acknowledges returned definitions before
closing its query connection and rolls back newly retained results on failure.
Read-only edit refusal uses LSP error `-32010`, mapped to MCP `READ_ONLY_SCOPE`.
Consumer identity is scoped to the
project session; the MCP adapter additionally binds it to its authorized task.
Read returns the descriptor plus `text`. Retain/release are idempotent per consumer.
Revalidation confirms the same admitted origin and revision before queries resume;
a changed revision reports unavailable and requires new navigation. Unknown,
expired, unauthorized and unreadable sources are explicit errors, never disk reads
chosen by client paths. Consumers are created by the server, not caller-selected.
VS Code uses a read-only text content provider, with the source language and no
save-back path. Disconnect may leave the immutable text visible, but blocks
semantic queries until revalidation. No content-change event may replace the old
revision under old positions. Closing the last consumer releases the snapshot;
one reader closing must not invalidate another reader. Edit operations and mixed
workspace edits are rejected in their entirety, including physical aliases.
Packaged Studio validation is excluded from this delivery; development tests must
exercise both VS Code and independent MCP navigation.
## 4. Result, Error and Operation Contracts