feat(pbs): resolve editorial chains and expose read-only external sources
This commit is contained in:
+19
@@ -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.
|
||||
|
||||
+10
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user