Add restricted generic trait companion contract

Author: DmytroMitin

README.md

@@ -182,6 +182,17 @@ paths. See the
 [structured annotated-class input view](docs/structured-annotated-class-input-view.md)
 and [handler authoring adapter](docs/annotated-class-view-handler-authoring-adapter.md).
 
+Prompt 85 adds one deliberately restricted repository fixture:
+`@externalRestrictedTraitApply trait Show[A]`. The shared decoder now exposes
+additive raw family/variance/bound-status projections, while an internal profile admits
+only a top-level non-sealed trait with one invariant ordinary unbounded type
+parameter and no constructor/value parameters. Its precompiled handler leases,
+creates, or merges the same-name companion and manually inserts
+`def apply[A](using instance: Show[A]): Show[A] = instance`; an existing direct
+`apply` wins. All prior handlers remain class-only, and this adds no quasiquotes
+or AUXify dependency. See the
+[restricted generic trait companion contract](docs/restricted-generic-trait-companion-contract.md).
+
 The packaged `pluginApi` boundary now has an exact-build, line-oriented JVM
 surface baseline at `project/experimental-plugin-api-surface-baseline.txt`.
 `verifyExperimentalPluginApiSurfaceBaseline` detects class, member descriptor,
@@ -204,10 +215,10 @@ state. See [`pluginApi` dependency-coordinate integrity](docs/plugin-api-depende
 
 Prompt 80 adopts the Prompt 79 feasibility result as a real source/project
 split. `pluginApi` is contract-only; the new unpublished `pluginTestMarkers`
-project owns all 37 repository fixture markers plus the one fixture-support
-class. Their logical two-JAR union remains byte-for-byte the committed Prompt
-77 baseline with normalized SHA-256
-`039a25870ed7265a657bb5262f86e0af13a35672f942db7a81d4ba66184217e0`.
+project owns all 38 repository fixture markers plus the one fixture-support
+class. Their logical two-JAR union remains the committed exact-build surface;
+Prompt 85 intentionally refreshes its normalized SHA-256 to
+`9985dbb9012c2ec8452e42a8282a97b41c71faf94eef76de848dd4b94b514c3f`.
 Marker consumers now name that artifact explicitly while handler-only paths
 retain only the API contract. See the
 [experimental plugin API source-project split](docs/experimental-plugin-api-source-project-split.md).

bootstrap-prompt.md

@@ -194,7 +194,10 @@ The current project state is a minimal Scala 3 research compiler-plugin project
   global-state comparison, and cleanup proof are implemented in
   `project/IndependentExternalSbtConsumer.scala` and its spec. No production
   publishing setting, public coordinate, workflow, source project, or stable
-  API is added.
+  API is added. Because the repository-wide production guard is
+  `ThisBuild / publish / skip := true`, the disposable publisher explicitly
+  sets `pluginApi / publish / skip := false` and
+  `plugin / publish / skip := false` only inside its copied source process.
 - Prompt 84 adds `project/ExternalApiPublicationReadiness.scala`, its 22-case
   spec, `docs/external-api-publication-readiness-decision.md`, and the explicit
   root task `verifyExternalApiPublicationReadiness`. The build sets
@@ -204,6 +207,15 @@ The current project state is a minimal Scala 3 research compiler-plugin project
   release mechanisms and production fixture contamination, and writes a
   line-oriented ignored-target report. Prompt 83 remains partial synthetic
   evidence only; no real coordinates or release implementation are added.
+- Prompt 85 adds one exact-build internal admission profile for
+  `externalRestrictedTraitApply`. The shared `AnnotatedClassView` decoder now
+  accepts raw class or trait templates and exposes additive definition-family,
+  type-parameter variance, ordinary-unbounded, and context-bound projections
+  while retaining the old constructor/factory/copy JVM shapes. The dedicated
+  precompiled handler manually builds one contextual companion `apply`, uses
+  the existing companion lease/create/merge and structured-output paths, and
+  keeps every previous handler on the class-only envelope. It adds no
+  quasiquotes or AUXify dependency and does not enable production publishing.
 - The build adds `Resolver.scalaNightlyRepository` because research plugins are only enabled on nightly or snapshot Scala 3 builds.
 - The plugin defines custom built-in marker annotations in `paradise3.gen` and `paradise3.debug`.
 - The experimental `pluginApi` project defines the handler contract,
@@ -212,7 +224,8 @@ The current project state is a minimal Scala 3 research compiler-plugin project
   `pluginTestMarkers` project owns `paradise3.externalDebug`,
   `externalCompanionDebug`, `externalSiblingDebug`, `externalLabel`,
   `externalTypedLabel`, `externalMarker`, fixture-only
-  `externalQuasiquotesTerm`, and the hostile protocol marker/support fixtures.
+  `externalQuasiquotesTerm`, fixture-only `externalRestrictedTraitApply`, and
+  the hostile protocol marker/support fixtures.
 - `paradise3.externalDebug`, `paradise3.externalCompanionDebug`, `paradise3.externalSiblingDebug`, `paradise3.externalLabel`, and `paradise3.externalTypedLabel` carry `@expander(...)` metadata naming their `demo` handlers, so the plugin can discover those handlers from precompiled marker annotations when `handlerClasspath` is explicit.
 - The current annotation-owned bridge is metadata-owned only. `externalDebug` names a precompiled `ParadiseAnnotationExpander`; it does not implement Scala 2 `macroTransform`, Scala 3 `MacroAnnotation.transform`, general same-module handlers, or quasiquote integration.
 - The focused same-module staging note records a hardened Prototype success for one internal, test-only, normalized different-file relationship shared by two consumers. Current source wins over stale output and child loaders are scoped and closed. The incremental-compilation follow-up records Outcome 4: a handler-only implementation change recompiles only the handler because the compiler callback has no direct source dependency and ordinary Zinc class relations are API-sensitive. General same-module support is deferred, no dependency-recording code is retained, and `pluginTestHandlers` remains the reliable baseline.
@@ -469,6 +482,7 @@ The current project state is a minimal Scala 3 research compiler-plugin project
   - `plugin-test-markers/src/main/scala/paradise3/externalTypedLabel.scala`
   - `plugin-test-markers/src/main/scala/paradise3/externalMarker.scala`
   - `plugin-test-markers/src/main/scala/paradise3/externalQuasiquotesTerm.scala`
+  - `plugin-test-markers/src/main/scala/paradise3/externalRestrictedTraitApply.scala`
   - `plugin-test-markers/src/main/java/paradise3/PreservedRuntimeMarker.java`
   - `plugin-test-markers/src/main/scala/paradise3/metadataEmpty.scala`
   - `plugin-test-markers/src/main/scala/paradise3/metadataMissing.scala`
@@ -494,10 +508,14 @@ The current project state is a minimal Scala 3 research compiler-plugin project
   - `plugin-test-handlers/src/main/scala/demo/ExternalDebugExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/LegacyExternalDebugExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/ExternalCompanionDebugExpander.scala`
+  - `plugin-test-handlers/src/main/scala/demo/ExternalRestrictedTraitApplyExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/ExternalSiblingDebugExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/ExternalLabelExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/ExternalTypedLabelExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/ExternalMarkerExpander.scala`
+  - `plugin-tests/src/main/scala/RestrictedGenericTraitApplyExample.scala`
+  - `plugin-tests/src/test/scala/RestrictedGenericTraitContractSpec.scala`
+  - `docs/restricted-generic-trait-companion-contract.md`
   - `plugin-test-handlers/src/main/scala/demo/DuplicateExternalDebugExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/GenNameExpander.scala`
   - `plugin-test-handlers/src/main/scala/demo/NotAnExpander.scala`
@@ -840,7 +858,7 @@ Create these files:
 241. `docs/experimental-plugin-api-source-project-split.md`
 242. `prompts/80.codex.experimental.plugin.api.contract.and.test.marker.source.project.split.prompt.md`
 243. `reviews/80_chatgpt_experimental_plugin_api_source_project_split_handoff/README.md`
-244. `plugin-test-markers/src/main/` (14 moved marker/support source files)
+244. `plugin-test-markers/src/main/` (15 marker/support source files)
 245. `plugin-api-handler-contract-probe/e2e/IndependentPackagedConsumer.scala`
 246. `project/IndependentPrecompiledHandlerPackagedConsumer.scala`
 247. `project/IndependentPrecompiledHandlerPackagedConsumerSpec.scala`
@@ -856,6 +874,19 @@ Create these files:
 257. `docs/task-owned-local-repository-external-sbt-consumer.md`
 258. `prompts/83.codex.task.owned.local.repository.external.sbt.consumer.staging.prompt.md`
 259. `reviews/83_chatgpt_task_owned_local_repository_external_sbt_consumer_handoff/`
+260. `project/ExternalApiPublicationReadiness.scala`
+261. `project/ExternalApiPublicationReadinessSpec.scala`
+262. `docs/external-api-publication-readiness-decision.md`
+263. `prompts/84.codex.external.api.publication.readiness.decision.and.no.publish.gate.prompt.md`
+264. `reviews/84_chatgpt_external_api_publication_readiness_decision_handoff/`
+265. `plugin-test-markers/src/main/scala/paradise3/externalRestrictedTraitApply.scala`
+266. `plugin-test-handlers/src/main/scala/demo/ExternalRestrictedTraitApplyExpander.scala`
+267. `plugin-tests/src/main/scala/RestrictedGenericTraitApplyExample.scala`
+268. `plugin-tests/src/test/scala/RestrictedGenericTraitContractSpec.scala`
+269. `docs/restricted-generic-trait-companion-contract.md`
+270. `input/17_quasiquotes_scala3_restricted_generic_trait_and_companion_contract_response.md`
+271. `prompts/85.codex.restricted.top.level.generic.trait.admission.and.companion.merge.contract.prompt.md`
+272. `reviews/85_chatgpt_restricted_generic_trait_companion_contract_handoff/`
 
 ## File Requirements
 
@@ -2654,12 +2685,12 @@ Create these files:
 
 - Keep the root aggregate exactly six projects by including the unpublished
   `pluginTestMarkers` project beside the retained five projects.
-- Keep five contract sources under `plugin-api/` and 14 moved marker/support
+- Keep five contract sources under `plugin-api/` and 15 marker/support
   sources under `plugin-test-markers/`; preserve packages/JVM names and never
   retain duplicate copies.
 - Keep `project/experimental-plugin-api-surface-baseline.txt` as the sole class
   category authority. Its two-JAR logical union must retain normalized SHA-256
-  `039a25870ed7265a657bb5262f86e0af13a35672f942db7a81d4ba66184217e0`.
+  `9985dbb9012c2ec8452e42a8282a97b41c71faf94eef76de848dd4b94b514c3f`.
 - Keep `PluginApiSourceProjectSplitPolicy`, the 18-case build-shape policy,
   split surface verifier, source-built candidate-byte proof, marker metadata
   proof, explicit marker consumer paths, expanded clean-resolution proof, and

docs/annotated-class-view-handler-authoring-adapter.md

@@ -85,6 +85,13 @@ hatch.
 | Five helper-backed fixtures | `withAnnotatedClassView` | helper-owned `Structured` | Current common path |
 | `ExternalMarkerExpander` | raw `annotatedClass` | raw `Expanded` | Retained power path |
 | `QuasiquotesConstructedTermExpander` | raw input plus exact peer adapter | raw/structured compiler trees under the exact artifact contract | Retained integration proof |
+| `ExternalRestrictedTraitApplyExpander` | `withAnnotatedClassView` plus bounded trait/type-parameter projections | low-level raw method construction wrapped in `Structured` | Prompt 85 repository-only fixture |
+
+Prompt 85 extends the same decoder with additive exact-build projections for
+raw class-versus-trait family, type-parameter variance, ordinary-unbounded
+status, and context-bound presence. Only `externalRestrictedTraitApply` selects
+the plugin-owned restricted trait admission profile; the five common
+helper-backed handlers remain class-only.
 
 ## Evidence boundary
 

docs/experimental-handler-contract-only-artifact-feasibility.md

@@ -19,14 +19,14 @@ After Prompt 80, the ordinary `pluginApi / Compile / packageBin` result is the
 source-built contract artifact:
 
 ```text
-bytes:   134654
-entries: 52
-classes: 39
+bytes:   148524
+entries: 58
+classes: 45
 Tasty:   9
-SHA-256: 9128b4561d9328576501a1b306fb39ecc8327df7dca699264d89d020d2eb3da4
+SHA-256: 08ca262f70e92040653f561098484d1db7e5fb90f31f2bd3b351979bc5f89b9c
 ```
 
-The separate unpublished marker artifact contains 38 classes and 36 Tasty
+The separate unpublished marker artifact contains 39 classes and 37 Tasty
 resources. Their logical union retains the Prompt 77 surface; neither copies
 entries from the other.
 
@@ -36,11 +36,11 @@ The candidate is:
 target/experimental-plugin-api-handler-contract/
   macroparadise-scala3-plugin-api-handler-contract_3-0.1.0-SNAPSHOT.jar
 
-bytes:   308506
-entries: 49
-classes: 39
+bytes:   342100
+entries: 55
+classes: 45
 Tasty:   9
-SHA-256: 2b93807da82fc33b745e484d02890bfd593856601df59f92cd5a449333cb1a84
+SHA-256: 999903e76c68ebcf8cab45550ea7ddb84ee0a9ce3dc2a71860014fcc6e1fe678
 ```
 
 Stored ZIP entries make the candidate larger than the compressed source-built
@@ -72,7 +72,7 @@ surface and compared with the committed Prompt 77 manifest. The normalized
 surface SHA remains exactly:
 
 ```text
-039a25870ed7265a657bb5262f86e0af13a35672f942db7a81d4ba66184217e0
+9985dbb9012c2ec8452e42a8282a97b41c71faf94eef76de848dd4b94b514c3f
 ```
 
 The candidate carrier retains runtime retention, `TYPE` and
@@ -96,15 +96,15 @@ diagnostics.
 
 ## All-current-handler compile proof
 
-All 14 sources under `plugin-test-handlers/src/main/scala/` are passed to one
+All 15 sources under `plugin-test-handlers/src/main/scala/` are passed to one
 direct pinned compiler invocation using only the candidate, the exact
 compiler/library universe, and JDK classes. Two clean repetitions both exit 0
-and produce the same 85-file inventory:
+and produce the same 87-file inventory:
 
 ```text
-class files:                              44
-Tasty files:                              41
-ParadiseAnnotationExpander implementations: 37
+class files:                              45
+Tasty files:                              42
+ParadiseAnnotationExpander implementations: 38
 ```
 
 No `paradise3/api`, compiler, Scala, plugin implementation, or fixture-marker

docs/experimental-plugin-api-source-project-split.md

@@ -29,13 +29,13 @@ pluginTests
 ```
 
 `pluginApi` remains rooted at `plugin-api/` and contains five source files. Its
-package owns exactly 38 `HANDLER_CONTRACT` classes, the one
+package owns exactly 44 `HANDLER_CONTRACT` classes, the one
 `METADATA_CARRIER`, nine Tasty resources, and standard JAR metadata.
 
 `pluginTestMarkers` is rooted at `plugin-test-markers/`, depends on
-`pluginApi` only for `paradise3.api.expander`, and is not published. Its 14
-source files own exactly 37 `INTEGRATION_FIXTURE_MARKER` classes, the one
-`INTEGRATION_FIXTURE_SUPPORT` class, and 36 Tasty resources. Packages and JVM
+`pluginApi` only for `paradise3.api.expander`, and is not published. Its 15
+source files own exactly 38 `INTEGRATION_FIXTURE_MARKER` classes, the one
+`INTEGRATION_FIXTURE_SUPPORT` class, and 37 Tasty resources. Packages and JVM
 names are unchanged. No moved source remains under `plugin-api/`, and neither
 artifact copies entries from the other.
 
@@ -44,10 +44,10 @@ artifact copies entries from the other.
 `project/experimental-plugin-api-surface-baseline.txt` remains the sole class
 classification authority. `PluginApiSourceProjectSplitPolicy` compares the two
 source-built JAR inventories with those categories, rejects duplicate entries
-or ownership reversal, verifies the five/14 source layout, and checks the
+or ownership reversal, verifies the five/15 source layout, and checks the
 metadata and constructor shapes of the moved fixtures.
 
-The marker proof covers all nine runtime metadata values, including empty and
+The marker proof covers all ten runtime metadata values, including empty and
 missing-handler values, without initializing `MetadataInitializationProbe`.
 It also preserves the generic `[A]` plus `String` constructor shape of
 `externalTypedLabel` and the runtime Java annotation shape of
@@ -59,24 +59,24 @@ Tasty entry.
 The surface verifier now reads contract classes from `pluginApi` and fixture
 classes from `pluginTestMarkers`, permits only the unavoidable standard
 manifest in both archives, and rejects all other duplicate entries. Their
-logical union renders byte-for-byte the committed Prompt 77 manifest:
+logical union renders byte-for-byte the committed exact-build manifest:
 
 ```text
 normalized surface SHA-256:
-039a25870ed7265a657bb5262f86e0af13a35672f942db7a81d4ba66184217e0
+9985dbb9012c2ec8452e42a8282a97b41c71faf94eef76de848dd4b94b514c3f
 
 committed/rendered manifest file SHA-256:
-13e46917255adee612dd0920b0c03b205aec2381fde8c7ca2700a3543c8a9e4a
+43ef7d2883571f4fc8235790813e3c9e9c8826c931335380965f84c6e63a551f
 ```
 
 Current source-built artifact evidence from the reviewed pinned run is:
 
 ```text
-pluginApi:          134654 bytes, 52 entries, 39 classes, 9 Tasty
-SHA-256:            9128b4561d9328576501a1b306fb39ecc8327df7dca699264d89d020d2eb3da4
+pluginApi:          148524 bytes, 58 entries, 45 classes, 9 Tasty
+SHA-256:            08ca262f70e92040653f561098484d1db7e5fb90f31f2bd3b351979bc5f89b9c
 
-pluginTestMarkers:  41887 bytes, 76 entries, 38 classes, 36 Tasty
-SHA-256:            8fe14a5124a690e57f7d8b150494d27d27803118b0dd1cce494f3d945b826562
+pluginTestMarkers:  43109 bytes, 78 entries, 39 classes, 37 Tasty
+SHA-256:            285054a9095cceb3db1743bdc534c8e0dfb285c62569550319e9d0ba97c85051
 ```
 
 JAR SHA values are build-output identities, not a published coordinate or a

docs/experimental-plugin-api-surface-baseline.md

@@ -51,12 +51,12 @@ line-oriented format is version 1 and contains:
 The current normalized SHA-256 is:
 
 ```text
-039a25870ed7265a657bb5262f86e0af13a35672f942db7a81d4ba66184217e0
+9985dbb9012c2ec8452e42a8282a97b41c71faf94eef76de848dd4b94b514c3f
 ```
 
-The baseline contains 38 handler-contract classes, one metadata carrier, 37
-integration fixture marker classes, one fixture-support class, 569
-public/protected member records, and 46 allowed resource records.
+The baseline contains 44 handler-contract classes, one metadata carrier, 38
+integration fixture marker classes, one fixture-support class, 658
+public/protected member records, and 47 allowed resource records.
 
 ## Surface categories
 
@@ -83,7 +83,7 @@ but is not itself a handler contract or marker annotation.
 Prompt 80 makes the baseline a logical union of two normally packaged JARs.
 `pluginApi` owns only `HANDLER_CONTRACT`, `METADATA_CARRIER`, nine contract
 Tasty resources, and standard metadata. The unpublished `pluginTestMarkers`
-owns only the 37 fixture-marker classes, one support class, 36 fixture Tasty
+owns only the 38 fixture-marker classes, one support class, 37 fixture Tasty
 resources, and standard metadata. The verifier rejects duplicate non-manifest
 entries, ownership reversal, unclassified classes, unexpected resources, or
 entries owned by:
@@ -98,8 +98,8 @@ scala3/
 tasty/
 ```
 
-The reviewed source-built `pluginApi` JAR has 39 classes and nine Tasty
-resources; `pluginTestMarkers` has 38 classes and 36 Tasty resources. Neither
+The reviewed source-built `pluginApi` JAR has 45 classes and nine Tasty
+resources; `pluginTestMarkers` has 39 classes and 37 Tasty resources. Neither
 copies a compiler, Scala library, plugin implementation, handler fixture,
 peer artifact, consumer output, or entries owned by the other project. Exact
 reviewed identities are recorded in
@@ -167,7 +167,7 @@ Prompt 79 used these categories as the sole filtering authority for an ignored,
 deterministic handler-contract-only feasibility artifact. Prompt 80 adopts the
 corresponding source boundary and proves that the source-built contract entry
 names and uncompressed bytes equal a freshly rendered candidate. It proves the
-38 handler-contract classes, metadata carrier, and their nine Tasty resources
+44 handler-contract classes, metadata carrier, and their nine Tasty resources
 are sufficient to compile and link every current precompiled handler while
 excluding repository markers and support. See
 [Experimental handler-contract-only artifact feasibility](experimental-handler-contract-only-artifact-feasibility.md).